cqbase.net · 中英双语

CQBase 上下文库

Context & Query Base

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 的示例,用作核验,不是官方固定口令。本次没有连接真实笔记库,因此不编造搜索结果。

  1. 打开一个不含私人日记或密钥的测试库,启用 Local REST API,把密钥只写进本地 MCP 配置。
  2. 确认 Obsidian 保持运行,客户端能看到 search 和 get_file_contents。
  3. 先明确告诉代理使用 Obsidian,再发送:Search the vault for notes that mention "weekly review". Summarize the matching notes. Do not append, patch, or delete anything.
  4. 自己打开那些笔记,核对摘要是否属实。若代理要写入或删除,先拒绝,直到你改用测试库并明确允许。

常见坑

  • Obsidian 没开,或插件没启用,连接被拒绝。issue #76(2026-11-15 仍为 open)就报告过 Connection refused。先确认插件正在监听,以及主机、端口与配置一致。
  • Claude 找不到 uvx。这是 README 写明的情况,请把 command 换成 which uvx 得到的绝对路径。
  • 与 mcp Python 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 为准。

订阅 CQBase 周刊

每周一封,介绍本周新收录的公开 AI 技能、提示词、MCP 和用法。可随时退订。我们不会把邮箱交给第三方作其营销之用。