Obsidian Web MCP

社区

通过 HTTPS 安全远程访问你的 Obsidian 仓库，支持 OAuth 2.0 认证。

分类: 文件系统第 3 / 24
Stars: ★ 183 热门
传输方式: Streamable HTTP
运行环境: Python 3.12+
凭据: 需要 API Key / 凭据
许可证: MIT
最近提交: 2 天前
工具数: 20

68FMRS · C

obsidian-web-mcp 是一个功能强大、安全设计良好的远程 MCP 服务器，专为 Obsidian 设计。它解决了本地 stdio 服务器无法从远程访问、以及 Obsidian Sync 文件损坏的问题。设置需要一定的技术知识，但文档详尽。适合需要跨设备访问笔记的高级用户。

最强项 · 文档质量 17/20 最弱项 · 可靠性 9/20

可靠性

9/20

安全与权限

16/20

维护活跃度

14/20

文档质量

17/20

安装易用性

12/20

查看各项评分依据

可靠性 9/20: 代码库包含大量测试（tests/ 目录），覆盖认证、配置、frontmatter、OAuth、工具函数和路径解析等关键路径，但未看到 CI 配置（如 GitHub Actions）或运行测试的验证证据。启动流程依赖于环境变量，未提供一键启动脚本，但文档详细说明了配置和启动步骤。因此，可靠性得分基于测试覆盖和代码结构，但缺乏实际运行验证，给予 9 分。
安全与权限 16/20: 实现了 OAuth 2.0 授权码 + PKCE 流程，密码强制要求，未设置密码时服务器拒绝授权（fail-closed）。路径遍历被阻止，写入采用原子操作，删除需要确认，并提供了审计日志。这些安全措施在源代码中有体现。未发现明显绕过或严重漏洞。因此，安全得分 16 分，扣分因为缺少对扩展机制的限制（尽管文档说明扩展是可信的），以及未看到实际安全审查或漏洞报告。
维护活跃度 14/20: 仓库有 158 星，11 个开放 issue，最近提交日期未知。README 提到私有漏洞报告渠道，但未提供贡献指南或变更日志。没有看到 CI 和发布流程。因此，维护得分 14 分，扣分因为缺乏明确的版本发布和更新路径。
文档质量 17/20: README 详细说明了架构、安全模型、工具、配置、部署方式（Tunnel、VPS）、扩展方法等，包含示例命令和配置说明。但没有提供故障排除指南或常见错误说明。文档整体质量高，有分层，但缺少一些运行时错误场景的指导。因此，文档得分 17 分。
安装易用性 12/20: 提供了快速开始、详细配置和多种部署方式（本地、Cloudflare Tunnel、VPS + Caddy），但需要手动设置环境变量和安装依赖，没有提供一键脚本。文档包含了示例命令，但缺乏对主流客户端（如 Claude）连接的具体配置示例（虽然提到了添加集成的步骤）。根据静态校准，没有真实 CI 和测试运行证据，设置得分限制在 15 分以下，实际给 12 分。

静态评测 · 未实际运行收录于 2026-08-07

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件写入 / 删除本地文件

适合谁

希望从任何设备安全远程访问 Obsidian 仓库的用户。
将 Claude.ai（网页版）或移动端与 Obsidian 集成。
需要与 Obsidian Sync 并发写入且避免文件冲突。

不适合谁

只需要本地 stdio MCP 访问，无远程需求。
不希望设置 OAuth 密码或使用 Cloudflare Tunnel 的用户。
对安全要求极高、不信任网络暴露的用户（尽管已加密）。

所需权限

读写 VAULT_PATH 指定的文件系统目录。
执行文件操作（移动、删除，软删除到 .trash）。
创建每日笔记、写入二进制文件。
维护内存中的 frontmatter 索引，可能更改索引文件。
访问网络（用于 Cloudflare Tunnel、心跳 URL）。

风险与副作用

凭证泄露风险：OAuth 密码或 MCP token 泄露可导致未授权访问。
路径遍历缓解并非万无一失，需保持更新。
扩展系统不受沙箱保护，加载不可信扩展可能带来全面风险。
审计日志是尽力而为，并非防篡改，运行时可能丢失记录。
错误配置可能导致服务器拒绝启动或暴露漏洞。

安装接入

准备工作

运行环境：Python 3.12+

VAULT_PATH 必填 Obsidian 笔记库的绝对路径，必填。

VAULT_MCP_TOKEN 必填密钥 256 位 bearer 令牌，可用 python -c "import secrets; print(secrets.token_hex(32))" 生成，必填。

VAULT_OAUTH_PASSWORD 必填密钥 OAuth 浏览器登录页的密码，未设置时服务器拒绝授权任何客户端（fail-closed），必填。

VAULT_OAUTH_CLIENT_SECRET 可选密钥 headless client_credentials 授权的客户端密钥；Claude/ChatGPT 浏览器流程不需要。

VAULT_MCP_HEARTBEAT_URL 可选密钥可选的在线监控推送 URL（如 Uptime Kuma），视为机密，不记录日志。

其他可选配置项（15 个）

VAULT_OAUTH_USERNAME 可选 OAuth 登录用户名，默认 obsidian。

VAULT_MCP_HOST 可选 HTTP 绑定地址，默认 127.0.0.1。

VAULT_MCP_PORT 可选 HTTP 监听端口，默认 8420。

VAULT_MCP_PATH 可选 MCP 传输挂载的 HTTP 路径，默认 /。

VAULT_MCP_ALLOWED_HOSTS 可选 DNS 重绑定保护允许的主机名列表（逗号分隔），远程部署时须设为隧道/代理主机名。

VAULT_MCP_FORWARDED_ALLOW_IPS 可选信任 X-Forwarded-* 头的客户端 IP，默认 127.0.0.1，切勿设为 *。

VAULT_MCP_PUBLIC_URL 可选服务器对外公布的规范来源（如 https://vault-mcp.yourdomain.com），用于固定 OAuth 发现 URL，反向代理部署建议设置。

VAULT_OAUTH_CLIENT_ID 可选 headless client_credentials 授权的客户端 ID，默认 vault-mcp-client。

VAULT_OAUTH_REDIRECT_URIS 可选静态客户端浏览器授权的回调 URI 白名单（逗号分隔），一般留空。

VAULT_DAILY_NOTES_FOLDER 可选日记工具使用的文件夹，为空表示笔记库根目录。

VAULT_DAILY_NOTES_FORMAT 可选日记文件名的 strftime 格式，默认 %Y-%m-%d。

VAULT_DAILY_NOTES_TEMPLATE 可选首次创建日记时前置的 strftime 模板。

VAULT_MCP_HEARTBEAT_INTERVAL 可选心跳间隔秒数，默认 60，仅在设置了心跳 URL 时生效。

VAULT_AUDIT_LOG_PATH 可选可选的追加式 JSONL 审计日志路径，必须位于笔记库之外，否则拒绝启动。

VAULT_AUDIT_LOG_INCLUDE_READS 可选是否也记录读取/搜索操作，默认关闭。

克隆仓库：git clone https://github.com/jimprosser/obsidian-web-mcp.git。
设置环境变量：VAULT_PATH（仓库路径）、VAULT_MCP_TOKEN（强令牌）、VAULT_OAUTH_PASSWORD（必填，用于浏览器登录）。
使用 uv run vault-mcp 运行服务器（默认绑定 127.0.0.1:8420）。
在 Claude（桌面或移动端）中添加集成，输入服务器 URL；Claude 会通过 OAuth 流自动注册并连接。

验证是否装好

启动服务器后运行 curl -s http://localhost:8420/.well-known/oauth-authorization-server 确认服务响应；在 Claude 的 Settings > Integrations 添加服务器 URL 并完成 OAuth 登录后，工具列表中应出现 vault_read、vault_search 等工具。

常见排障

检查 VAULT_OAUTH_PASSWORD 是否设置，否则服务器拒绝授权。
远程部署时设置 VAULT_MCP_ALLOWED_HOSTS 为你的主机名，否则 DNS 重绑定保护会拒绝请求。
使用反向代理时设置 VAULT_MCP_PUBLIC_URL 以固定 OAuth 重定向。
确保 VAULT_AUDIT_LOG_PATH 在仓库之外且可写，否则启动失败。
验证 Cloudflare Tunnel 和 Caddy 配置，确保端口正确。

试试这样问

连接成功后，可以直接对 AI 助手这样说：

搜索我的笔记库里所有提到“项目计划”的文件
把今天日记里追加一段：完成了 MCP 服务器的部署
读取 notes/today.md 的内容和 frontmatter
帮我总结一下笔记库的卫生状况，比如缺失 frontmatter 和断链的文件

工具能力 20

vault_read 只读

读取文件，返回内容、元数据和解析后的 YAML frontmatter。

vault_batch_read 只读

一次读取多个文件，优雅处理缺失文件。

vault_write 写入

写文件，可选合并 frontmatter，自动创建父目录。

vault_write_binary 写入

从 base64 内容写入允许的二进制文件（如图片/PDF），强制媒体类型白名单和大小限制，原子写入。

vault_edit 写入

通过有序精确文本替换打补丁（token 高效的局部编辑），支持 dry-run 预览。

vault_append 写入

在文件末尾追加内容，无需重发现有正文，文件缺失时创建。

vault_batch_frontmatter_update 写入

批量更新多个文件的 YAML frontmatter 字段，不触碰正文。

vault_search 只读

全文搜索（优先使用 ripgrep，否则回退到 Python）。

展开其余 12 个工具

vault_search_frontmatter 只读

按字段值、子串或字段存在性查询内存 frontmatter 索引。

vault_list 只读

列出目录内容，支持递归深度、glob 过滤和文件/目录切换。

vault_move 写入

在仓库内移动或重命名文件或目录。

vault_delete 破坏性

软删除文件（移动到 .trash/ ），需要显式确认。

vault_canvas_read 只读

读取 .canvas 文件，返回解析后的节点和边。

vault_canvas_add_node 写入

向 .canvas 文件追加节点（缺失时创建），自动生成 id，保留未知字段。

vault_canvas_add_edge 写入

向现有 .canvas 文件追加边，两端必须引用现有节点 id。

vault_daily_note_path 只读

解析今天的日记路径，基于配置的文件夹/格式。

vault_daily_note_read 只读

读取今天的日记，不存在时返回错误（不创建）。

vault_daily_note_append 写入

追加到今天的日记，缺失时根据模板创建。

vault_analytics_summary 只读

紧凑的仓库健康摘要：缺失 frontmatter、损坏的 wikilink、近似重复标签变体和非 UTF-8 文件的计数和示例。

vault_analytics_findings 只读

获取一个分析类别的详细发现（frontmatter_missing、required_frontmatter_missing、broken_wikilinks、suspicious_tag_variants、encoding_issues、oversized_files）。

使用场景

从任何地方（包括手机）通过 Claude 访问你的 Obsidian 笔记。

使用网页版 Claude 或 Claude Mobile，无需本地 stdio 服务器。

安全地与 Obsidian Sync 并发写入，避免文件损坏。

将你的仓库作为 MCP 连接器提供给 Claude 应用。

支持客户端

Claude Desktop

Claude Mobile

Claude Web

依据项目文档列出，未经本站实测。

详细介绍

obsidian-web-mcp 是一个安全的、可远程访问的 MCP 服务器，让 LLM（如 Claude）能够从任何地方读写你的 Obsidian 仓库——包括桌面、手机或任意网络。它通过 HTTP 运行，使用 OAuth 2.0 认证，并通过 Cloudflare Tunnel 暴露服务，因此你的机器不会直接暴露在互联网上。服务器直接读写磁盘上的 Markdown 文件，解析 YAML frontmatter，维护内存索引以支持快速查询，并提供全文搜索功能。默认采用原子写入，确保与 Obsidian Sync 兼容。