obsidian-mcp-server

一个极简的 Obsidian 插件，在 Obsidian 内部运行一个 MCP（模型上下文协议）服务器，使用 Streamable HTTP 传输。它暴露了四个工具：list_notes、read_note、write_note、search_notes。

完全在你的机器上运行（绑定到 127.0.0.1）——除非你将远程客户端指向它（你不应该这样做），否则不会有数据离开你的电脑。

为什么采用这种方法

Obsidian 桌面应用基于 Electron，插件可以使用 Node 集成，因此插件可以打开一个真正的 http.Server 并直接与 MCP 通信——无需外部进程，也无需额外保持一个 npx 服务器运行。

Related MCP server: obsidian-mcp

构建（Windows）

# 1. Put this folder inside your vault's plugin directory, e.g.:
#    <vault>\.obsidian\plugins\obsidian-mcp-server\

cd <vault>\.obsidian\plugins\obsidian-mcp-server
npm install
npm run build

这会生成 main.js，与 manifest.json 放在一起。然后在 Obsidian 中：设置 → 社区插件 → 打开“MCP Server”开关。你应该会看到一条通知：MCP server listening on http://127.0.0.1:8123/mcp。

打开插件设置以更改端口或设置 Bearer 令牌。

连接 Claude Desktop

Claude Desktop 的本地 mcpServers 配置期望的是 stdio 命令，而不是原始 URL，因此要用 mcp-remote 桥接到 HTTP 端点（按需通过 npx 安装，需要 Node.js）：

编辑 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8123/mcp"]
    }
  }
}

如果你在插件设置中设置了 Bearer 令牌，请将其作为请求头传递：

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "http://127.0.0.1:8123/mcp",
        "--header", "Authorization:Bearer YOUR_TOKEN"
      ]
    }
  }
}

从托盘图标退出 Claude Desktop，然后重新打开。此时应出现一个工具图标，显示这四个 Obsidian 工具。

调试

• 使用 MCP Inspector 直接测试服务器，而不通过 Claude Desktop：运行 npx @modelcontextprotocol/inspector 并连接到 http://127.0.0.1:8123/mcp。

• Obsidian 的开发者控制台（Ctrl+Shift+I）会显示插件的 console.error 输出，包括请求错误。

扩展

在 main.ts 的 buildMcpServer() 中添加更多工具——例如，包装 app.metadataCache 以进行 frontmatter/标签查询，或者包装 app.workspace 以获取“当前打开的是哪条笔记”。每个工具只是一个名称、一个 zod 输入模式，以及一个返回 { content: [...] } 的异步处理函数。

备注 / 注意事项

• 清单中的 isDesktopOnly: true——这不会在 Obsidian 移动版上加载，因为那里没有原生的 http 模块。

• 这里的无状态传输模式（每个请求一个全新的 StreamableHTTPServerTransport）是最简单的选择，适合单个本地客户端。如果你需要多个并发客户端并保持合适的会话连续性，可以添加一个以 Mcp-Session-Id 为键的传输映射——参见 MCP TypeScript SDK 的“会话管理”示例。

• Bearer 令牌是一种基本的共享密钥检查，并非真正的认证。由于服务器只绑定到 127.0.0.1，主要威胁模型是“你机器上的其他本地进程”，而该令牌确实能应对这一威胁。