适合谁
- 已经使用 Obsidian Local REST API 的个人知识库用户。
- 需要结构化笔记搜索和局部编辑的 MCP 客户端用户。
- 希望通过读取和写入目录白名单限制 vault 范围的部署。
O
60FMRS · C
资料显示该服务器面向 Obsidian vault 的 MCP 读写、搜索和精细编辑，功能覆盖较完整，并提供目录权限控制和只读开关。部署前必须配置 Local REST API 与 API key；公开 HTTP 部署尤其需要配置认证并审慎限制写权限。
obsidian-mcp-server 是由 cyanheads 维护的开源 MCP 服务器，可通过 Obsidian Local REST API 读取、创建、搜索和精细编辑笔记、标签及 frontmatter。服务器提供 STDIO 和 Streamable HTTP 传输，包含 14 个工具和 3 个资源，版本为 3.2.9，采用 Apache-2.0 许可证。
工具能力
obsidian_get_note
按原始内容、完整结构、文档地图或单个区块读取笔记。
obsidian_list_notes
列出指定 vault 路径下的笔记和子目录，并支持递归深度及过滤器。
obsidian_list_tags
列出整个 vault 中的标签及使用次数。
obsidian_list_commands
列出 Obsidian 命令面板命令；需启用 OBSIDIAN_ENABLE_COMMANDS。
obsidian_search_notes
按文本、JSONLogic 或可用时的 Omnisearch BM25 搜索 vault，并支持游标分页。
obsidian_write_note
创建笔记，或替换指定区块；覆盖已有整篇文件需要显式设置 overwrite。
obsidian_append_to_note
向笔记末尾或指定标题、区块、frontmatter 字段追加内容。
obsidian_patch_note
对标题路径、区块引用或 frontmatter 字段执行追加、前置插入或替换。
obsidian_replace_in_note
在单篇笔记正文中执行字面量或正则搜索替换。
obsidian_manage_frontmatter
原子地获取、设置或删除单个 frontmatter 字段。
obsidian_manage_tags
在 frontmatter、正文内联位置或两者中添加、删除或列出标签。
obsidian_delete_note
永久删除笔记，并在客户端支持时请求人工确认。
obsidian_open_in_ui
在 Obsidian 应用界面中打开文件。
obsidian_execute_command
按命令 ID 执行 Obsidian 命令面板命令；需显式启用。
安装接入
安装并启用 Obsidian Local REST API 插件 v4.0.0 或更高版本，在插件设置中生成 API key。使用 Bun v1.3.11 或更高版本，或 Node.js v24 以上版本。将 OBSIDIAN_API_KEY 填入客户端配置；默认连接 http://127.0.0.1:27123。也可从 npm 使用 npx，或克隆仓库后运行 bun install。使用 Streamable HTTP 时运行 start:http，默认地址为 http://127.0.0.1:3010/mcp。
claude_desktop_config.json
{"mcpServers":{"obsidian-mcp-server":{"type":"stdio","command":"bunx","args":["obsidian-mcp-server@latest"],"env":{"MCP_TRANSPORT_TYPE":"stdio","MCP_LOG_LEVEL":"info","OBSIDIAN_API_KEY":"your-local-rest-api-key"}}}}
选型与风险
不适合谁
- 未安装或未启用 Obsidian Local REST API 插件的环境。
- 需要云端多用户数据库或远程协作平台的团队。
- 不应授予笔记写入权限或不接受本地 API key 管理的场景。
所需权限
- 需要 OBSIDIAN_API_KEY，用于访问 Obsidian Local REST API。
- 默认可访问整个 vault；可用 OBSIDIAN_READ_PATHS 和 OBSIDIAN_WRITE_PATHS 设置目录白名单。
- 写操作可被 OBSIDIAN_READ_ONLY=true 全局禁用。
- HTTP 部署可配置 none、jwt 或 oauth 认证；JWT 模式需要 OBS_AUTH_SECRET_KEY 的对应配置项 MCP_AUTH_SECRET_KEY。
风险与副作用
- 写操作可能修改或删除 vault 内容；obsidian_delete_note 会永久删除笔记。
- 命令面板命令可能具有破坏性，因此默认关闭，启用后应谨慎授权。
- 默认 HTTP API 使用本机地址；公开部署若不配置 MCP 认证，调用者可能借助服务器访问 vault。
- HTTPS 插件端点使用自签名证书，默认不验证 TLS；应理解相应的传输安全风险。
- 标签列表和 obsidian://tags 资源是全 vault 范围，可能暴露读取目录之外的标签名称。
常见排障
- 确认 Local REST API 插件已安装、启用且版本至少为 4.0.0。
- 检查 OBSIDIAN_API_KEY 是否正确，并确认 OBSIDIAN_BASE_URL 与插件实际端口一致。
- 使用 HTTP 端口时，在插件设置中启用 Non-encrypted (HTTP) Server；使用 HTTPS 时通常保持 OBSIDIAN_VERIFY_SSL=false。
- 若 Omnisearch 模式缺失，确认插件 HTTP 服务可达，并重启服务器以重新探测。
- 若出现 path_forbidden，检查读取或写入路径白名单及 OBSIDIAN_READ_ONLY 设置。
- HTTP 连接问题可检查 MCP_HTTP_HOST、MCP_HTTP_PORT、MCP_HTTP_ENDPOINT_PATH 和 MCP_AUTH_MODE。
使用场景
让 MCP 客户端读取和整理 Obsidian 笔记。
按文本、JSONLogic 或 Omnisearch 搜索个人知识库。
对标题、区块引用、标签和 frontmatter 进行精细更新。
在受控目录中创建、追加、替换或删除笔记。
支持客户端
Claude Desktop完整支持
Cursor完整支持
VS Code完整支持