Advanced Obsidian MCP Server

适用于Obsidian的高级MCP工具

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

由obsidiantools库驱动的关键高级功能：

• 发现保险库树状结构以映射您的笔记层级
• 针对大型语言模型（LLM）的友好型见解的笔记连接网络X（NetworkX）图分析
• 直接从AI执行Obsidian命令
• 带元数据和链接详情的批处理文件读取
• 实时访问您当前激活的笔记以获取上下文信息
• 在新的 Obsidian 窗口中打开笔记/文件，实现无缝编辑

这种设置让人工智能代理与您并肩工作，通过高效地浏览和增强您的知识库来提高生产力。

组件

工具

服务器实现了多个工具以与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使用支持“glob”和“regexp”模式匹配的JsonLogic查询进行复杂的文档搜索

笔记管理

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

- 注：此工具需要 Dataview 社区插件以使其功能正常。请确保在您的Vault中安装Dataview插件。

保险库分析

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

示例提示

首先指导Claude（或任何其他MCP客户端）使用Obsidian是个好主意。这样它就会始终调用这个工具。例如，

这样的提示用法如下：

• *“在Obsidian中，我正在撰写的报告中，详细阐述一下营销部分”*

- 克劳德将会使用 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 工具，你会设置 INCLUDE_TOOLS="obsidian_understand_vault,obsidian_simple_search" 在 .env 文件中或在服务器配置中。

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

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

{
  "mcp-obsidian-advanced": {
    "command": "uvx",
    "args": [
      "mcp-obsidian-advanced"
    ],
    "env": {
      "OBSIDIAN_API_KEY": "%3Cyour_api_key_here%3E",
      "OBSIDIAN_HOST": "",
      "OBSIDIAN_PORT": "",
      "OBSIDIAN_VAULT_PATH": "
",
      "INCLUDE_TOOLS": ""
    }
  }
}

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

1. 创建一个 .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

快速入门

安装

通过Smithery进行安装

通过自动方式为Claude Desktop安装高级Obsidian MCP服务器 Smithery（注：此词并非标准英语词汇，可能是特定语境或虚构作品中的词汇，若按音译处理，则为“史密特里”，但具体含义需根据上下文确定）：

npx -y @smithery/cli install @ToKiDoO/mcp-obsidian-advanced --client claude

Obsidian REST API

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

• 你可以在Obsidian中进入“社区插件”页面，搜索并安装它。

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

Claude Desktop（克劳德桌面版）

在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": "",
        "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": "",
        "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服务器是通过标准输入输出（stdio）运行的，因此调试可能会具有挑战性。为了实现最佳调试效果 根据经验，我们强烈建议使用 MCP 检查器。

您可以通过以下方式启动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