MCP server for Obsidian

Obsidian MCP 服务

通过 Local REST API 社区插件与 Obsidian 交互的 MCP 服务。

组件

工具

该服务实现了多个用于与 Obsidian 交互的工具：

• list_files_in_vault：列出 Obsidian 库根目录中的所有文件和目录
• list_files_in_dir：列出指定 Obsidian 目录中的所有文件和目录
• get_file_contents：返回库中单个文件的内容。
• search：在库中的所有文件内搜索与指定文本查询匹配的文档
• patch_content：相对于标题、块引用或 frontmatter 字段，在现有笔记中插入内容。
• append_content：将内容追加到库中的新文件或现有文件。
• delete_file：删除库中的文件或目录。

示例提示词

最好先指示 Claude 使用 Obsidian。这样它就会始终调用该工具。

然后使用如下提示词：

• 获取最近一次架构讨论笔记的内容并进行总结
• 搜索所有提及 Azure CosmosDb 的文件，并快速向我说明提及它的上下文
• 总结最近的会议笔记，并将其放入名为“summary meeting.md”的新笔记中。添加一段简介，以便我通过电子邮件发送。

要求

• Python >= 3.11
• mcp Python SDK >=1.1.0,<2.0.0（在 pyproject.toml 中固定）。mcp-obsidian 当前通过 mcp 1.x 低级 Server API（@app.list_tools() / @app.call_tool()）注册工具处理程序，而该 API 已在 mcp 2.0 中移除。如果安装不受版本限制的 mcp>=2.0，导入时会因 AttributeError: 'Server' object has no attribute 'list_tools' 而崩溃。

配置

Obsidian REST API 密钥

配置 Obsidian REST API 密钥有两种方式。

1. 添加到服务配置中（推荐）

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

有时 Claude 无法检测到 uv / uvx 的位置。在这种情况下，可以使用 which uvx 查找完整路径，并将其粘贴到上面的配置中。

2. 在工作目录中创建 .env 文件，并填写以下必需变量：

OBSIDIAN_API_KEY=your_api_key_here
OBSIDIAN_HOST=your_obsidian_host
OBSIDIAN_PORT=your_obsidian_port

注意：

• 可以在 Obsidian 插件配置中找到 API 密钥
• 如果未指定，默认端口为 27124
• 如果未指定，默认主机为 127.0.0.1

快速开始

安装

Obsidian REST API

需要运行 Obsidian REST API 社区插件：https://github.com/coddingtonbear/obsidian-local-rest-api

在设置中安装并启用该插件，然后复制 API 密钥。

Claude Desktop

MacOS：~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "uv",
      "args": [
        "--directory",
        "<dir_to>/mcp-obsidian",
        "run",
        "mcp-obsidian"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>",
        "OBSIDIAN_HOST": "<your_obsidian_host>",
        "OBSIDIAN_PORT": "<your_obsidian_port>"
      }
    }
  }
}

{
  "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>"
      }
    }
  }
}

Docker

你可以在容器中运行该服务，而不必在本地安装 uv/Python。

1. 将 .env.example 复制为 .env，并填写 Obsidian REST API 密钥：

cp .env.example .env

默认情况下，OBSIDIAN_HOST 设置为 host.docker.internal，它会在容器内解析为 你的主机（适用于 Linux、Mac 和 Windows）。

2. 构建镜像：

docker compose build

3. 将 MCP 客户端指向该容器。由于 MCP 使用标准输入/输出传输 JSON-RPC， 客户端必须在标准输入已连接且不使用伪终端的情况下运行它——请使用 docker compose run --rm -T，而不是 docker compose up：

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

你也可以手动运行它，以确认容器能正常启动：

docker compose run --rm -T mcp-obsidian

（它会等待从标准输入接收 JSON-RPC 消息；按 Ctrl+C 退出）

开发

构建

准备分发软件包：

1. 同步依赖项并更新锁文件：

uv sync

调试

由于 MCP 服务通过 stdio 运行，调试可能会比较困难。为了获得最佳调试体验，我们强烈建议使用 MCP Inspector。

你可以通过 npm 使用以下命令启动 MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-obsidian run mcp-obsidian

启动后，Inspector 会显示一个 URL，你可以在浏览器中访问该 URL 并开始调试。

你也可以使用以下命令查看服务日志：

tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-obsidian.log