Obsidian MCP Server

什么是 Obsidian MCP Server？

这个 Obsidian MCP 服务器（mcp-obsidian，作者 Markus Pfundstein）是一个开源 Python 服务器，借助 Local REST API 社区插件，让 Claude 等 MCP 客户端列出、读取、搜索、写入和删除 Obsidian 仓库（vault）中的笔记。

它是社区项目，并非 Obsidian 官方出品。服务器从不直接读写你的仓库文件，所有操作都通过运行在 Obsidian 应用内的 Obsidian Local REST API 插件完成，因此使用时 Obsidian 必须保持打开。它以 mcp-obsidian 发布在 PyPI 上，采用 MIT 许可证，通过 uvx 运行。

如何使用 Obsidian MCP Server？

前置条件：

• 已安装并启用 Local REST API 社区插件的 Obsidian，并从插件设置中复制 API 密钥。
• uv（用于 uvx）以及 Python 3.11 或更高版本。

环境变量：

• OBSIDIAN_API_KEY：Local REST API 插件中的密钥（必填）
• OBSIDIAN_HOST：默认 127.0.0.1
• OBSIDIAN_PORT：默认 27124

可以在 MCP 服务器配置中设置（推荐），也可以写在工作目录下的 .env 文件中。

Claude Desktop

在 macOS 上编辑 ~/Library/Application Support/Claude/claude_desktop_config.json，在 Windows 上编辑 %APPDATA%/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "uvx",
      "args": ["mcp-obsidian"],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}

如果 Claude 找不到 uvx，运行 which uvx，把完整路径填为 command。

Claude Code、Cursor 和 VS Code

README 只记录了 Claude Desktop。由于这是标准的 stdio 服务器，其他客户端可以用相同的 env 值运行同样的 uvx mcp-obsidian 命令，例如写入 .cursor/mcp.json 或 .vscode/mcp.json。在 Claude Code 中，将其添加为启动 uvx mcp-obsidian 并设置这三个变量的 stdio 服务器即可。

Docker

如果不想安装 uv 和 Python，可以把 .env.example 复制为 .env，运行 docker compose build，再让客户端指向容器。MCP 需要连接 stdin 且不能分配 TTY，所以要用 run --rm -T，而不是 up：

{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "docker",
      "args": ["compose", "-f", "<dir_to>/mcp-obsidian/docker-compose.yml", "run", "--rm", "-T", "mcp-obsidian"]
    }
  }
}

在容器中，OBSIDIAN_HOST 默认为 host.docker.internal，以便访问你电脑上的 Obsidian。

Obsidian MCP Server 的主要功能

• 浏览仓库：列出根目录或任意文件夹。
• 读取单条笔记或批量读取多条，批量读取时输出会拼接在一起。
• 带上下文的简单文本搜索，以及高级 JsonLogic 查询和按标签搜索。
• 精确编辑：相对某个标题、块引用或 frontmatter 字段插入内容，或追加到文件末尾。
• 创建或整体覆盖文件，删除文件或文件夹（需显式确认参数）。
• 支持周期笔记：获取当前的每日、每周、每月、每季度或每年笔记，或最近的周期笔记。
• 查看最近修改的文件和 frontmatter。
• 设计上完全本地：笔记留在你的电脑上，只通过插件的本地 API 访问。

Obsidian MCP Server 工具

当前源码注册了 15 个工具，全部以 obsidian_ 为前缀；mcp.so 页面和 README 列出的是最初的七个。

• 导航与读取：obsidian_list_files_in_vault、obsidian_list_files_in_dir、obsidian_get_file_contents、obsidian_batch_get_file_contents。
• 搜索：obsidian_simple_search（带上下文的文本匹配）、obsidian_complex_search（JsonLogic 查询，例如对路径使用 glob 模式）、obsidian_search_by_tag。
• 写入：obsidian_append_content、obsidian_patch_content（在标题、块或 frontmatter 目标处 append、prepend 或 replace）、obsidian_put_content（替换整个文件）。
• 删除：obsidian_delete_file 需要 confirm: true。
• 元数据与周期笔记：obsidian_get_frontmatter、obsidian_get_periodic_note、obsidian_get_recent_periodic_notes、obsidian_get_recent_changes。

Obsidian MCP Server 的使用场景

README 建议先告诉 Claude 使用 Obsidian，这样它会稳定地调用这些工具。

• 回顾会议：“获取最近一次架构讨论会的笔记内容并做总结。”
• 在整个仓库中调研：“搜索所有提到 Azure CosmosDb 的文件，并简要说明它们是在什么背景下提到的。”
• 写回笔记：“总结上次的会议记录，写入新笔记 'summary meeting.md'，并加一段引言，方便我通过邮件发送。”
• 每日回顾：“打开今天的日记，在 Tasks 标题下加上我最重要的三件事。”
• 每周整理：“列出本周修改过的笔记，并给仍是草稿的笔记打上标签。”

Obsidian MCP Server 与替代方案对比

Obsidian 没有官方 MCP 服务器，可选方案都来自社区。mcp-obsidian 通过 Local REST API 插件工作，因此能做到按标题打补丁、支持周期笔记和 JsonLogic 搜索，代价是 Obsidian 必须处于运行状态。把普通的 Filesystem MCP Server 指向仓库文件夹，则无需打开 Obsidian，但它只认识文件，不理解 frontmatter 或周期笔记等 Obsidian 概念。其他笔记应用可参考 Apple Notes MCP 或 Notion MCP Server。

Obsidian MCP Server 常见问题排查

• 报错 AttributeError: 'Server' object has no attribute 'list_tools'：该服务器需要 mcp Python SDK 1.x（>=1.1.0,<2.0.0），装了 mcp>=2.0 就会崩溃，请通过 uvx mcp-obsidian 使用锁定版本的包。
• Claude 无法启动服务器：Claude 有时找不到 uv/uvx，请在配置中填写 which uvx 得到的完整路径。
• 连接被拒绝或超时：确认 Obsidian 已打开、Local REST API 插件已启用，且 OBSIDIAN_HOST/OBSIDIAN_PORT 与插件一致（默认 127.0.0.1:27124）。
• Docker 容器退出或卡住：使用 docker compose run --rm -T 运行，而不是 docker compose up，因为 MCP 通过 stdin 通信。
• 调试：使用 MCP Inspector（npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-obsidian run mcp-obsidian），或在 macOS 上 tail ~/Library/Logs/Claude/mcp-server-mcp-obsidian.log。