Obsidian MCP Server

社区

通过 MCP 管理 Obsidian 知识库。

分类: 文件系统第 8 / 24
Stars: ★ 697 非常热门
传输方式: stdio（本地进程） · Streamable HTTP
运行环境: Bun 1.3.0+ · Node.js 24+ · Docker
凭据: 需要 API Key / 凭据
许可证: Apache-2.0
最近提交: 21 天前
工具数: 14

60FMRS · C

资料显示该服务器面向 Obsidian vault 的 MCP 读写、搜索和精细编辑，功能覆盖较完整，并提供目录权限控制和只读开关。部署前必须配置 Local REST API 与 API key；公开 HTTP 部署尤其需要配置认证并审慎限制写权限。

最强项 · 文档质量 16/20 最弱项 · 可靠性 10/20

可靠性

10/20

安全与权限

11/20

维护活跃度

10/20

文档质量

16/20

安装易用性

13/20

查看各项评分依据

可靠性 10/20: 清单与文档对 STDIO、Streamable HTTP、14 个工具、资源、路径策略和错误行为的描述总体一致，启动参数和超时也有明确配置。由于仅提供清单和 README，未提供可核验的源代码、CI 工作流或测试结果，无法确认初始化、工具列表握手、依赖兼容性及边界错误处理，因此扣分，且按静态校准不超过 12 分。
安全与权限 11/20: API 密钥用途明确，默认连接本机，提供读写路径限制、全局只读开关，并将命令执行设为关闭。扣分原因是 HTTP 认证默认 none、默认读写整个 vault、TLS 校验默认关闭，且删除操作仅在客户端支持 elicitation 时请求确认；远程部署的实际隔离仍依赖操作者配置。未发现提示中的红线风险，因此不按红线处理。
维护活跃度 10/20: 项目有明确仓库归属、Apache-2.0 许可证、版本号 3.2.9、npm 发布路径和问题跟踪入口，显示出可维护性基础。由于没有提交历史、发布频率、CI、依赖更新记录、漏洞响应渠道或 issue 响应证据，无法证明持续维护，因此仅给中等分数。
文档质量 16/20: README 覆盖先决条件、Bun/Node 与 npx 安装、STDIO/HTTP 客户端配置、环境变量、工具参数、分页、限制、路径策略、危险命令和 Docker 部署注意事项，证据较完整。仍缺少可核验的源代码和测试支持，故无法确认文档准确性；故障排查、平台差异和安全配置示例也不够系统，未给满分。
安装易用性 13/20: 提供 Bun 和 npx 两条安装路径、主流客户端配置示例、必要插件/API 密钥说明以及 HTTP 启动方式，基本流程清晰。扣分原因是必须预先安装并配置 Obsidian 插件、生成密钥并处理 HTTP/自签名 TLS 设置，HTTP 认证和生产部署还需额外手动配置；没有源代码、CI 或端到端连接证据，按静态校准不超过 15 分。

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

查看 FMRS 评分方法 →

选型与风险

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

适合谁

已经使用 Obsidian Local REST API 的个人知识库用户。
需要结构化笔记搜索和局部编辑的 MCP 客户端用户。
希望通过读取和写入目录白名单限制 vault 范围的部署。

不适合谁

未安装或未启用 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 范围，可能暴露读取目录之外的标签名称。

安装接入

准备工作

运行环境：Bun 1.3.0+ · Node.js 24+ · Docker

OBSIDIAN_API_KEY 必填密钥必填的 Bearer 令牌，在 Obsidian 的 Settings → Community Plugins → Local REST API 插件设置中生成。

MCP_AUTH_SECRET_KEY 可选密钥当 MCP_AUTH_MODE=jwt 时必填，至少 32 字符的共享密钥。

其他可选配置项（14 个）

OBSIDIAN_BASE_URL 可选 Local REST API 插件的基础 URL，默认 http://127.0.0.1:27123；HTTPS 端口为 https://127.0.0.1:27124。

OBSIDIAN_VERIFY_SSL 可选是否校验 TLS 证书，默认 false，因插件使用自签名证书。

OBSIDIAN_REQUEST_TIMEOUT_MS 可选每次请求的超时毫秒数，默认 30000。

OBSIDIAN_ENABLE_COMMANDS 可选设为 true 时启用 obsidian_list_commands 与 obsidian_execute_command 命令面板工具对，默认关闭。

OBSIDIAN_READ_PATHS 可选可选的逗号分隔仓库相对文件夹读取白名单，如 'public/,projects/'；未设置则允许全库读取。

OBSIDIAN_WRITE_PATHS 可选可选的逗号分隔写入白名单，语法同 OBSIDIAN_READ_PATHS；未设置则允许全库写入。

OBSIDIAN_READ_ONLY 可选设为 true 时为全局只读开关，拒绝所有写操作并抑制命令面板工具，适合共享或公开部署。

OBSIDIAN_OMNISEARCH_URL 可选 Omnisearch 插件 HTTP 服务地址覆盖项，仅在插件不在默认端口 51361 时需要。

MCP_TRANSPORT_TYPE 可选传输方式：stdio 或 http，默认 stdio。

MCP_HTTP_HOST 可选 HTTP 服务器主机名，默认 127.0.0.1。

MCP_HTTP_PORT 可选 HTTP 服务器端口，默认 3010。

MCP_HTTP_ENDPOINT_PATH 可选 MCP JSON-RPC 端点路径，默认 /mcp。

MCP_AUTH_MODE 可选 HTTP 传输的认证模式：none、jwt 或 oauth，默认 none。

MCP_LOG_LEVEL 可选日志最低级别（RFC 5424），默认 info。

安装并启用 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"}}}}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "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"
      }
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add obsidian-mcp-server -e MCP_TRANSPORT_TYPE=stdio -e MCP_LOG_LEVEL=info -e OBSIDIAN_API_KEY=your-local-rest-api-key -- bunx obsidian-mcp-server@latest

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

在 MCP 客户端连接后，工具列表中应出现 obsidian_get_note、obsidian_list_notes 等工具；可调用 obsidian_get_note 读取一篇已知路径的笔记，返回内容即证明与 Local REST API 插件的连接正常。

常见排障

确认 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。

试试这样问

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

列出我 Obsidian 仓库里的所有标签及使用次数。
在 projects/ 目录下搜索包含 'Q3 roadmap' 的笔记。
打开笔记 'Daily Notes/2025-01-15'，在 ## Tasks 标题下追加 'Review PR #42'。
把笔记 'meeting-notes' 里所有的 'Acme Corp' 替换为 'Globex'，要区分大小写。

工具能力 14

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 字段执行追加、前置插入或替换。

展开其余 6 个工具

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 命令面板命令；需显式启用。

使用场景

让 MCP 客户端读取和整理 Obsidian 笔记。

按文本、JSONLogic 或 Omnisearch 搜索个人知识库。

对标题、区块引用、标签和 frontmatter 进行精细更新。

在受控目录中创建、追加、替换或删除笔记。

支持客户端

Claude Desktop

Cursor

VS Code

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

详细介绍

obsidian-mcp-server 是由 cyanheads 维护的开源 MCP 服务器，可通过 Obsidian Local REST API 读取、创建、搜索和精细编辑笔记、标签及 frontmatter。服务器提供 STDIO 和 Streamable HTTP 传输，包含 14 个工具和 3 个资源，版本为 3.2.9，采用 Apache-2.0 许可证。