MCP Obsidian Advanced

🚀 高级Obsidian MCP服务器

高级MCP服务器，可通过本地REST API社区插件与Obsidian进行交互。它使AI代理（如Claude）能够深入了解你的知识库结构、链接和内容，而不仅仅局限于基本的读写操作。

由obsidiantools库支持的主要高级功能包括：

• 发现知识库树状结构，映射笔记层次关系
• 对笔记连接进行NetworkX图分析，为大语言模型提供友好的见解
• 直接从AI执行Obsidian命令
• 批量读取文件及其元数据和链接详情
• 获取当前活动笔记，提供实时上下文
• 在新的Obsidian窗口中打开笔记/文件，实现无缝编辑

这种设置使AI代理能够与你协同工作，通过高效导航和增强你的知识库来提高生产力。

✨ 主要特性

工具

服务器实现了多个与Obsidian交互的工具：

核心文件操作

• obsidian_list_files_in_dir：列出Obsidian特定目录中的所有文件和文件夹
• obsidian_batch_get_files：返回知识库中一个或多个笔记（.md文件）的内容和元数据
• obsidian_put_file：在知识库中创建新文件或更新现有文件的内容
• obsidian_append_to_file：向知识库中的新文件或现有文件追加内容
• obsidian_patch_file：相对于标题、块引用或前置元数据字段，将内容插入现有笔记中
• obsidian_delete_file：从知识库中删除文件或文件夹

搜索操作

• obsidian_simple_search：在知识库的所有文件中简单搜索与指定文本查询匹配的文档
• obsidian_complex_search：使用JsonLogic查询进行复杂搜索，支持'glob'和'regexp'模式匹配

笔记管理

• obsidian_get_active_note：获取Obsidian中当前活动笔记的内容和元数据
• obsidian_periodic_notes：获取指定周期（每日、每周、每月、每季度、每年）的当前周期笔记
• obsidian_recent_periodic_notes：获取指定周期类型的最近周期笔记
• obsidian_recent_changes：获取知识库中最近修改的文件

  ⚠️ 重要提示

  此工具需要Dataview社区插件才能正常工作。请确保在你的知识库中安装了Dataview插件。

知识库分析

• obsidian_understand_vault：全面了解知识库结构，包括目录树和笔记连接的NetworkX图
• obsidian_open_files：在新窗口中打开知识库中的一个或多个文件
• obsidian_list_commands：列出你可以在Obsidian界面中运行的所有可用命令
• obsidian_execute_commands：在Obsidian界面中执行一个或多个命令

示例提示

最好先指示Claude（或任何其他MCP客户端）使用Obsidian。然后它将始终调用该工具。例如：

• “扩展我目前在Obsidian中正在处理的报告的营销部分”
  • Claude将使用obsidian_get_active_note读取笔记，然后编辑该笔记。
• “搜索所有提及Azure CosmosDb的文件，并快速向我解释其提及的上下文”
• “总结上次会议笔记，并将其放入一个新的笔记‘summary meeting.md’中。添加一个引言，以便我可以通过电子邮件发送。”

📦 安装指南

环境变量

对于此MCP服务器，需要配置2个必需的环境变量：

• OBSIDIAN_API_KEY：通过安装Obsidian REST API插件并进入设置来获取此密钥。
• OBSIDIAN_VAULT_PATH：必须设置你的知识库的绝对路径，以便工具（如obsidian_understand_vault）正常工作。

此外，还有3个可选的环境变量可以更改：

• OBSIDIAN_HOST：可以在Obsidian REST API插件设置中更改。根据插件的默认设置，默认为127.0.0.1。
• OBSIDIAN_PORT：可以在Obsidian REST API插件设置中更改。根据插件的默认设置，默认为27124。
• INCLUDE_TOOLS：此变量控制哪些工具可供使用。
  • 写入你要包含的工具名称（上面列出的名称），用逗号分隔。
  • 例如，如果你只想要obsidian_understand_vault和obsidian_simple_search工具，你可以在.env文件或服务器配置中设置INCLUDE_TOOLS="obsidian_understand_vault,obsidian_simple_search"。

有两种方法可以使用Obsidian REST API密钥配置环境：

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

{
  "mcp-obsidian-advanced": {
    "command": "uvx",
    "args": [
      "mcp-obsidian-advanced"
    ],
    "env": {
      "OBSIDIAN_API_KEY": "%3Cyour_api_key_here%3E",
      "OBSIDIAN_HOST": "<your_obsidian_host>",
      "OBSIDIAN_PORT": "<your_obsidian_port>",
      "OBSIDIAN_VAULT_PATH": "</path/to/your/vault>",
      "INCLUDE_TOOLS": ""
    }
  }
}

⚠️ 重要提示

有时Claude在检测uv / uvx的位置时会出现问题。在这种情况下，你可以使用which uvx查找并将完整路径粘贴到上述配置中。

2. 在工作目录中创建一个.env文件，包含以下变量（仅OBSIDIAN_API_KEY和OBSIDIAN_VAULT_PATH是必需的）：

OBSIDIAN_API_KEY=your_api_key_here
OBSIDIAN_HOST=your_obsidian_host
OBSIDIAN_PORT=your_obsidian_port
OBSIDIAN_VAULT_PATH=/path/to/your/vault
INCLUDE_TOOLS=name_of_tool1,name_of_tool2,...

⚠️ 重要提示

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

安装步骤

Obsidian REST API

你需要运行Obsidian REST API社区插件：https://github.com/coddingtonbear/obsidian-local-rest-api 你可以通过在Obsidian中进入“社区插件”并搜索来安装它。在设置中安装并启用它，然后复制API密钥。

Claude桌面版

• 在MacOS上：~/Library/Application\ Support/Claude/claude_desktop_config.json
• 在Windows上：%APPDATA%/Claude/claude_desktop_config.json

已发布服务器配置：

{
  "mcpServers": {
    "mcp-obsidian-advanced": {
      "command": "uvx",
      "args": [
        "mcp-obsidian-advanced"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>",
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault/"
      }
    }
  }
}

开发/未发布服务器配置：

{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "uv",
      "args": [
        "--directory",
        "/dir/to/mcp-obsidian-advanced",
        "run",
        "mcp-obsidian"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>",
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault/"
      }
    }
  }
}

📚 详细文档

obsidiantools库和Obsidian REST API的附加文档

obsidiantools库和Obsidian REST API的附加文档可以在docs目录中找到。

• obsidiantools_in_15_minutes_documentation.md是一个ipynb文件，演示了obsidiantools的用例。
• obsidian_rest_api_documentation.yaml是一个yaml文件，演示了Obsidian REST API的用例。

构建

要准备用于分发的软件包：

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

uv sync

调试

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

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

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

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

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

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