cyanheads/obsidian-mcp-server

Read, write, search, and surgically edit Obsidian vault notes, tags, and frontmatter via MCP. STDIO or Streamable HTTP.

概述

obsidian‑mcp‑server 是一个桥接器，让 AI 代理（或任何兼容 MCP 的客户端）能够读取和编辑存储在 Obsidian 仓库中的笔记。它通过 Obsidian Local REST API 插件进行通信，并通过简单的 stdio 接口或轻量级 HTTP 服务器暴露一组 MCP 工具 和 资源 URL。服务器处理身份验证、文件夹级权限以及丰富的操作集，例如：

获取笔记（完整内容、单个标题或解析后的文档映射）
列出笔记、标签或命令面板条目
使用纯文本、JSONLogic 或 BM25（通过 Omnisearch 插件）搜索笔记
创建、追加、修补或替换章节、块和 front-matter
管理标签和 front-matter 键
删除笔记（可选用户确认）并在 Obsidian UI 中打开笔记。

所有响应都是 JSON-RPC 风格的对象，包含详细的错误代码和恢复提示，便于自主代理消费和操作。

主要特性

特性	功能
基于 MCP 的 API	实现模型上下文协议（MCP），使任何 MCP 客户端（Claude Desktop、Cursor、VS Code、自定义机器人）都能通过 stdio 或 HTTP 调用工具。
细粒度权限	文件夹范围的读写策略、只读模式以及可选的 JWT/OAuth 认证保护仓库。
丰富的笔记操作	写入整个文件、替换单个标题、块或 front-matter 字段，并执行基于正则表达式的搜索替换。
标签和 front-matter 管理	添加/删除/列出标签（front-matter、内联或两者）并获取/设置/删除任意 front-matter 键。
搜索灵活性	文本搜索、JSONLogic 查询或 BM25 排序的 Omnisearch（如果安装了 Omnisearch 插件）。
代理友好的输出	错误包含 `reason`、JSON-RPC 代码和 `recovery.hint`；修改工具报告大小差异和歧义数据。
可插拔存储和日志	内存、文件系统、Supabase、Cloudflare KV/R2/D1 后端；结构化日志，可选 OpenTelemetry 追踪。
多种部署选项	通过 Bun、Node（`npx`）、Docker 或作为 Streamable HTTP 服务器运行。

典型使用流程

设置 – 安装 Obsidian Local REST API 插件，生成 API 密钥，并配置 OBSIDIAN_API_KEY（可选 OBSIDIAN_BASE_URL）。
启动服务器 – 使用 bun run start:http 启动 HTTP 端点，或使用 bunx obsidian-mcp-server@latest 启动 stdio。
调用工具 – 兼容 MCP 的客户端发送 JSON-RPC 请求，例如 obsidian_get_note 获取笔记，obsidian_append_to_note 添加项目符号，或 obsidian_search_notes 查找相关内容。
处理响应 – 客户端读取结构化结果，检查错误上的 recovery.hint，并可能发出后续调用（例如，通过 obsidian_delete_note 确认删除）。
迭代 – 代理可以链式调用工具，在仓库内自主构建、编辑和组织知识。

安装与快速开始

# 克隆并安装（首选 Bun）
git clone https://github.com/cyanheads/obsidian-mcp-server.git
cd obsidian-mcp-server
bun install

# 复制环境模板并添加 API 密钥
cp .env.example .env
# 编辑 .env → 设置 OBSIDIAN_API_KEY=你的密钥

# 通过 stdio（Bun）或 Docker 运行
bunx obsidian-mcp-server@latest   # stdio
# 或
docker run -i --rm -e OBSIDIAN_API_KEY=… ghcr.io/cyanheads/obsidian-mcp-server:latest

对于 HTTP：

MCP_TRANSPORT_TYPE=http OBSIDIAN_API_KEY=… bun run start:http
# 服务器现在位于 http://127.0.0.1:3010/mcp

谁可能使用这个？

AI 代理 需要读写存储在 Obsidian 中的个人知识库。
自动化脚本 用于批量笔记更新、标签清理或定期笔记生成。
开发者工具 希望通过标准协议将 Obsidian 仓库暴露给外部 IDE 或 CLI 工具。
研究管道 将 Obsidian 仓库视为结构化数据存储，并需要编程访问。

限制与注意事项

依赖 Obsidian Local REST API 插件；没有它服务器无法运行。
某些操作（例如，在 Windows CRLF 文件上写入标题）在旧版插件上存在已知问题。
在 API 级别删除笔记是不可逆的；只有 Obsidian 的本地回收站可以恢复它们。
服务器不提供自己的搜索引擎 – 如果安装了 Omnisearch 插件，它会转发到该插件。
权限在文件夹级别强制执行；配置错误的 OBSIDIAN_READ_PATHS/OBSIDIAN_WRITE_PATHS 可能意外阻止访问。

许可证

Apache 2.0 – 免费使用、修改和分发。