Obsidian MCP 服务器

通过 Local REST API (本地 REST API) 社区插件与 Obsidian 交互的 MCP (Model Context Protocol) 服务器。

组件

工具

该服务器实现了多个工具以与 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' 中。添加一个介绍，以便我可以通过电子邮件发送。

配置

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

开发

构建

为了准备用于分发的包：

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

uv sync

调试

由于 MCP 服务器通过 stdio (标准输入输出) 运行，调试可能具有挑战性。为了获得最佳的调试体验，我们强烈建议使用 MCP Inspector。

您可以通过 npm 使用此命令启动 MCP Inspector：

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

启动后，Inspector 将显示一个 URL，您可以在浏览器中访问它以开始调试。

您也可以使用此命令查看服务器日志：

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

mcp-obsidian 快速上手指南

环境准备

• 系统要求：支持 macOS 或 Windows（Linux 未明确支持）
• 前置依赖：
  • 已安装 Obsidian
  • 已安装并启用 Obsidian 社区插件：Local REST API
  • 已安装 uv（推荐使用国内镜像加速安装）：

    # 国内用户可使用以下命令加速安装 uv
    curl -LsSf https://astral.sh/uv/install.sh | UV_INSTALL_DIR=~/.local/bin sh
    

  • （可选）如使用 Claude Desktop，需确保其版本支持 MCP 协议

安装步骤

1. 获取 Obsidian REST API 密钥
   在 Obsidian 中打开 Local REST API 插件设置，复制生成的 API Key。

2. 配置 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_api_key_here>",
           "OBSIDIAN_HOST": "127.0.0.1",
           "OBSIDIAN_PORT": "27124"
         }
       }
     }
   }
   

   💡 若 uvx 路径无法识别，可通过 which uvx 获取完整路径并替换 command 字段。

3. （可选）使用 .env 文件配置
   在工作目录创建 .env 文件替代环境变量配置：

   OBSIDIAN_API_KEY=your_api_key_here
   OBSIDIAN_HOST=127.0.0.1
   OBSIDIAN_PORT=27124
   

基本使用

启动 Claude Desktop 后，即可通过自然语言调用 Obsidian 工具。以下为简单示例：

• 查询文件内容

  “获取最近一次架构会议笔记的内容并总结”

• 全文搜索

  “搜索所有提到 ‘Azure CosmosDb’ 的文件，并说明上下文”

• 创建摘要笔记

  “总结上次会议记录，并保存为新笔记 ‘summary meeting.md’，加上适合邮件发送的引言”

工具将自动调用对应功能（如 get_file_contents、search、append_content 等），无需手动输入命令。