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社區插件才能正常工作。請確保在你的知識庫中安裝該插件。

知識庫分析

• 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