MCP
Obsidian MCP
通过 Obsidian 的 REST API 社区插件,让 MCP 客户端读写你的笔记库。
MarkusPfundstein/mcp-obsidian 是 MIT 许可的 MCP 服务器,经由 Obsidian 的 REST API 社区插件与笔记库交互。代理因此可能读取或改写你的笔记。
笔记库里常有日记和密钥备忘。先用一个隔离的测试库,关掉不需要的写权限。不要把生产库的 API 令牌交给远端代理环境。
推荐来源:
- @beamnxw 在 2026 年 9 月 15 日 的帖子里提到了这个项目(数字采集于 2026 年 11 月 15 日:633 次喜欢,105 次转发)。
本页是导读,不是原文。
解决什么问题
Obsidian MCP(仓库 MarkusPfundstein/mcp-obsidian)通过 Obsidian 的 Local REST API 社区插件,让 MCP 客户端读写你的笔记库。它并不直接扫描磁盘上的库目录,而是向插件提供的本地 HTTP 接口发请求。因此,Obsidian 必须开着,并且该插件已经启用。
官方 README 列出的工具包括:list_files_in_vault、list_files_in_dir、get_file_contents、search、patch_content、append_content 和 delete_file。其中后三项会改笔记,delete_file 还能删除目录。
适合谁
适合已经在用 Obsidian,并希望 Claude Desktop 或其他 MCP 客户端查询、整理笔记的人。项目使用 MIT 许可。要求 Python 3.11 或更新版本。
笔记库里常有日记和密钥备忘。请先用一个隔离的测试库,关掉不需要的写权限,不要把生产库的 API 令牌交给远端代理环境。
怎么装
核验日期为 2026-11-15(Asia/Shanghai)。步骤来自仓库 README。
先在 Obsidian 中安装并启用社区插件 Local REST API,再从插件设置里复制 API 密钥。默认主机是 127.0.0.1,默认端口是 27124;若你改过插件里的值,配置里也要一起改。
README 写明的客户端配置主要针对 Claude Desktop。macOS 路径是 ~/Library/Application Support/Claude/claude_desktop_config.json,Windows 路径是 %APPDATA%/Claude/claude_desktop_config.json。已发布包装使用 uvx:
{
"mcpServers": {
"mcp-obsidian": {
"command": "uvx",
"args": ["mcp-obsidian"],
"env": {
"OBSIDIAN_API_KEY": "<YOUR_OBSIDIAN_API_KEY>",
"OBSIDIAN_HOST": "<your_obsidian_host>",
"OBSIDIAN_PORT": "<your_obsidian_port>"
}
}
}
}官方还提到,Claude 有时找不到 uv 或 uvx。这时可用 which uvx 查出绝对路径,把 command 改成这条路径。第二种方式是在工作目录放 .env,写入 OBSIDIAN_API_KEY、OBSIDIAN_HOST 和 OBSIDIAN_PORT;官方仍把写进服务器配置的方式列为首选。
仓库也提供 Docker 配置。因为 MCP 走 stdio,客户端必须用 docker compose run --rm -T,不能用 docker compose up。从容器访问本机插件时,示例把 OBSIDIAN_HOST 设为 host.docker.internal。
README 没有给出 Cursor 或 Claude Code 的现成命令。其他接受标准 mcpServers 条目的客户端,可以沿用上面的 uvx 和环境变量,但本文不编造未经官方写出的启动命令。
一个实际例子
下面的提示词改写自 README 的示例,用作核验,不是官方固定口令。本次没有连接真实笔记库,因此不编造搜索结果。
- 打开一个不含私人日记或密钥的测试库,启用 Local REST API,把密钥只写进本地 MCP 配置。
- 确认 Obsidian 保持运行,客户端能看到
search和get_file_contents。 - 先明确告诉代理使用 Obsidian,再发送:
Search the vault for notes that mention "weekly review". Summarize the matching notes. Do not append, patch, or delete anything. - 自己打开那些笔记,核对摘要是否属实。若代理要写入或删除,先拒绝,直到你改用测试库并明确允许。
常见坑
- Obsidian 没开,或插件没启用,连接被拒绝。issue #76(2026-11-15 仍为 open)就报告过
Connection refused。先确认插件正在监听,以及主机、端口与配置一致。 - Claude 找不到
uvx。这是 README 写明的情况,请把command换成which uvx得到的绝对路径。 - 与
mcpPython SDK 2.0 不兼容。README 要求mcp>=1.1.0,<2.0.0。若按未加约束的mcp>=2.0安装,会在导入时出现AttributeError: 'Server' object has no attribute 'list_tools'。issue #155 和 issue #156 记录过同一类失败(均已关闭,并以 README 中的版本约束为准)。 - 路径处理上的安全报告。issue #150(2026-11-15 仍为 open)报告文件路径可能被拼到预期库范围之外。本文不复述复现步骤。在该问题仍开放时,更应使用隔离测试库,不要把生产库令牌交给不可信的代理环境。
delete_file和写入类工具默认可用。若你只想查询,应在客户端关闭这些工具,或先不要把生产库接进去。
FAQ
为什么必须先装 Local REST API 插件?
因为这个 MCP 服务器不直接读库目录,而是调用该插件的 HTTP 接口。插件没运行时,工具调用没有可用的后端。密钥也在插件设置里,不在 MCP 仓库里。
默认端口一定是 27124 吗?
官方写明:未指定时默认端口是 27124,默认主机是 127.0.0.1。若你在插件设置里改过,MCP 配置必须同步修改,否则会出现连接失败。
官方支持 Cursor 或 Claude Code 吗?
README 只详细写了 Claude Desktop 和 Docker。它没有提供 Cursor 或 Claude Code 的专用命令。若某个客户端使用标准的 mcpServers 配置,理论上可以沿用同一组 uvx 和环境变量,但本文不把这一点写成已经官方核验过的安装路径。
可以把令牌交给远程代理吗?
不建议。令牌能让持有者通过插件访问笔记库,包括读取和(在工具启用时)修改或删除。官方示例把服务跑在本机,并指向 127.0.0.1。生产库令牌不要放进远端或共享环境。
搜索或读取失败时先看什么?
先看 Obsidian 是否仍在运行、插件是否启用、密钥是否完整粘贴,以及主机端口是否一致。若服务器根本没有启动,再检查 uvx 路径和 mcp 包版本是否仍低于 2.0。
来源与许可
仓库 MarkusPfundstein/mcp-obsidian 使用 MIT 许可。它依赖的 Obsidian Local REST API 是单独的社区插件。本文依据 2026-11-15 查阅的 README,用自己的话写成,供 CQBase 上下文库使用。若环境变量、Python 或 mcp 版本要求有变,以仓库 README 为准。