JinDaGe - mcp-obsidian-advanced MCP Details

article

README

🚀 高级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社区插件才能正常工作。请确保在你的知识库中安装该插件。

知识库分析

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密钥配置环境：

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

{
  "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查找并将完整路径粘贴到上述配置中。

在工作目录中创建一个.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的使用案例。

构建

要准备分发软件包，请执行以下步骤：

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

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

mcp-obsidian-advanced