Obsidian Api MCP Server

🚀 Obsidian MCP Server

Obsidian MCP Server 是一個基於模型上下文協議（MCP）的服務器，藉助 Obsidian 的 Local REST API 插件，能讓 AI 智能體在你的 Obsidian 知識庫中進行復雜的知識發現和分析。

🚀 快速開始

前提條件

1. 在你的 Obsidian 知識庫中安裝 Obsidian Local REST API 插件。
2. 在 Obsidian 設置中配置並啟用該插件。
3. 記錄下 API URL（默認：https://localhost:27124）和你設置的 API 密鑰（如果有的話）。

安裝步驟

從 PyPI 安裝（推薦）

# 從 PyPI 安裝
pip install obsidian-api-mcp-server

# 或者使用 uv
uv pip install obsidian-api-mcp-server

添加到 MCP 配置

將以下內容添加到你的 MCP 客戶端配置（例如 Claude Desktop）中：

{
  "mcpServers": {
    "obsidian-api-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "obsidian-api-mcp-server>=1.0.1",
        "obsidian-api-mcp"
      ],
      "env": {
        "OBSIDIAN_API_URL": "https://localhost:27124",
        "OBSIDIAN_API_KEY": "your-api-key-here"
      }
    }
  }
}

從源代碼安裝（用於開發）

# 克隆倉庫
git clone https://github.com/pmmvr/obsidian-api-mcp-server
cd obsidian-api-mcp-server

# 使用 uv 安裝
uv pip install -e .

# 或者使用 pip 安裝
pip install -e .

配置

設置 Obsidian API 的環境變量：

# 必需：Obsidian API URL（默認使用 HTTPS）
export OBSIDIAN_API_URL="https://localhost:27124"  # 默認值

# 可選：如果你配置了認證，設置 API 密鑰
export OBSIDIAN_API_KEY="your-api-key-here"

⚠️ 重要提示

避免將 OBSIDIAN_API_KEY 硬編碼到腳本中，或者提交到版本控制系統。建議使用 .env 文件（本項目的 .gitignore 已包含該文件）和 python-dotenv 庫來管理你的 API 密鑰，或者使用操作系統或 shell 管理的環境變量。

💡 使用建議

服務器默認使用 HTTPS，並禁用對本地 Obsidian 實例常用的自簽名證書的 SSL 證書驗證。如果需要使用 HTTP 連接，請設置 OBSIDIAN_API_URL="http://localhost:27123"。

運行

啟動 MCP 服務器：

obsidian-mcp

✨ 主要特性

這個服務器能將你的 Obsidian 知識庫轉變為 AI 智能體強大的知識基礎，支持複雜的多步驟工作流程，例如：

• “從我的 'Projects/Planning' 文件夾中檢索標題包含 'roadmap' 或 'timeline'、且創建於 4 月 1 日之後的筆記，然後分析這些筆記中的任何阻礙或依賴關係，並給出綜合的風險評估以及源筆記的引用”
• “查找上個月所有帶有 'research' 或 'analysis' 標籤的筆記，掃描其內容中的不完整部分或未解決的問題，然後與我的 'Team/Expertise' 筆記進行交叉引用，以建議哪些同事可以幫助解決每個差距”
• “獲取 'Leadership/Quarterly' 文件夾中包含 'budget' 或 'headcount' 的會議筆記的完整內容，分析分配給我部門的行動項，並創建一個帶有源筆記引用的時間線”

服務器的高級過濾、正則表達式支持和完整內容檢索功能，使智能體能夠完成那些手動操作需要花費數小時的細緻知識工作。

💻 使用示例

可用工具

服務器提供了三個強大的工具：

search_vault - 高級搜索

具有靈活的過濾器和完整內容檢索功能：

• query - 在筆記內容中進行文本或正則表達式搜索（可選）
• query_type - 搜索類型："text"（默認）或 "regex"
• search_in_path - 將搜索範圍限制在特定文件夾路徑
• title_contains - 根據筆記標題中的文本進行過濾（字符串、數組或 JSON 字符串）
• title_match_mode - 如何匹配多個術語："any"（OR）或 "all"（AND）
• tag - 根據標籤進行過濾（字符串、數組或 JSON 字符串 - 搜索前置元數據和內聯 # 標籤）
• tag_match_mode - 如何匹配多個標籤："any"（OR）或 "all"（AND）
• context_length - 返回的內容量（設置為較大值以獲取完整內容）
• include_content - 布爾值，用於檢索所有匹配筆記的完整內容
• created_since/until - 根據創建日期進行過濾
• modified_since/until - 根據修改日期進行過濾
• page_size - 每頁的結果數量
• max_matches_per_file - 限制每個筆記的匹配數量

主要特性：

• 當未提供 query 時，自動返回僅基於過濾器搜索的完整內容。
• include_content=True 強制在任何搜索中檢索完整內容。
• 支持正則表達式模式，用於複雜的文本匹配（OR 條件、不區分大小寫的搜索等）。

get_note_content - 獲取筆記內容

通過路徑檢索特定筆記的完整內容和元數據。

browse_vault_structure - 瀏覽知識庫結構

高效導航知識庫的目錄結構：

• path - 要瀏覽的目錄（默認為知識庫根目錄）
• include_files - 布爾值，是否包含文件（默認：False，為了提高速度僅顯示文件夾）
• recursive - 布爾值，是否瀏覽所有嵌套目錄

基礎搜索示例

1. 在特定文件夾中按標題查找筆記：

search_vault(
  search_in_path="Work/Projects/",
  title_contains="meeting"
)

2. 查找標題包含多個術語（OR 邏輯）的筆記：

search_vault(
  title_contains=["foo", "bar", "fizz", "buzz"],
  title_match_mode="any"  # 默認值
)

3. 查找標題包含所有指定術語（AND 邏輯）的筆記：

search_vault(
  title_contains=["project", "2024"],
  title_match_mode="all"
)

4. 獲取所有近期筆記的完整內容：

search_vault(
  modified_since="2025-05-20",
  include_content=True
)

5. 帶上下文的文本搜索：

search_vault(
  query="API documentation",
  search_in_path="Engineering/",
  context_length=500
)

6. 按標籤搜索筆記：

search_vault(
  tag="project"
)

7. 使用正則表達式進行 OR 條件搜索：

search_vault(
  query="foo|bar",
  query_type="regex",
  search_in_path="Projects/"
)

8. 使用正則表達式搜索分配給特定人員的任務：

search_vault(
  query="(TODO|FIXME|ACTION).*@(alice|bob)",
  query_type="regex",
  search_in_path="Work/Meetings/"
)

高級多步驟工作流示例

戰略項目分析

# 步驟 1: 獲取所有項目文檔
search_vault(
  search_in_path="Projects/Infrastructure/",
  title_contains=["planning", "requirements", "architecture"],
  title_match_mode="any",
  include_content=True
)

# 步驟 2: 查找相關技術討論
search_vault(
  tag=["infrastructure", "technical-debt"],
  tag_match_mode="any",
  modified_since="2025-04-01",
  include_content=True
)

智能體可以進一步分析依賴關係、識別風險並建議資源分配

會議行動項挖掘

# 獲取所有近期會議筆記的完整內容
search_vault(
  search_in_path="Meetings/",
  title_contains=["standup", "planning", "retrospective"],
  title_match_mode="any",
  created_since="2025-05-01",
  include_content=True
)

智能體掃描內容以查找行動項，提取分配信息，並創建時間跟蹤

研究差距分析

# 查找包含問題或差距的研究筆記
search_vault(
  query="(TODO|QUESTION|INVESTIGATE|UNCLEAR)",
  query_type="regex",
  tag=["research", "analysis"],
  tag_match_mode="any",
  include_content=True
)

# 與團隊專業知識進行交叉引用
search_vault(
  search_in_path="Team/",
  tag=["expertise", "skills"],
  tag_match_mode="any",
  include_content=True
)

智能體識別知識差距並建議可以提供幫助的團隊成員

知識庫結構探索

# 快速查看組織結構
browse_vault_structure(recursive=True)

# 深入查看特定區域
browse_vault_structure(
  path="Projects/CurrentSprint/",
  include_files=True,
  recursive=True
)

基於標籤的知識映射

# 查找包含多個標籤（AND 邏輯）的筆記
search_vault(
  tag=["project", "urgent"],
  tag_match_mode="all",
  include_content=True
)

# 查找包含任何相關標籤（OR 邏輯）的筆記
search_vault(
  tag=["architecture", "design", "implementation"],
  tag_match_mode="any",
  modified_since="2025-04-15"
)

🔧 技術細節

開發

# 安裝測試依賴
uv pip install -e ".[test]"

# 啟動服務器
python -m obsidian_mcp.server

# 運行測試
uv run behave features/blackbox_tests.feature
# 或者使用測試運行器
python run_tests.py

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。