Obsidian MCP

🚀 Obsidian MCP 服務器

Obsidian MCP 服務器是一個基於模型上下文協議（MCP）的服務器，它能讓像 Claude 這樣的 AI 助手與你的 Obsidian 知識庫進行交互。該服務器藉助 Local REST API 插件，提供了讀取、創建、搜索和管理 Obsidian 筆記的工具。

🚀 快速開始

快速安裝

1. 安裝並配置 Obsidian：

   • 在 Obsidian 中安裝 Local REST API 插件。
   • 在“設置”>“社區插件”中啟用該插件。
   • 進入“設置”>“Local REST API”。
   • 複製你的 API 密鑰（在步驟 2 中會用到）。

2. 配置你的 AI 工具：

   Claude Desktop

   編輯你的 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "obsidian": {
         "command": "uvx",
         "args": ["obsidian-mcp"],
         "env": {
           "OBSIDIAN_REST_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

   Cursor IDE

   在你的 Cursor 設置中添加以下內容：

   • 項目特定設置：項目目錄下的 .cursor/mcp.json
   • 全局設置：主目錄下的 ~/.cursor/mcp.json

   {
     "mcpServers": {
       "obsidian": {
         "command": "uvx",
         "args": ["obsidian-mcp"],
         "env": {
           "OBSIDIAN_REST_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

   然後：打開“設置”→“Cursor 設置”→啟用 MCP。

   Windsurf IDE

   編輯你的 Windsurf 配置文件：

   • 位置：~/.codeium/windsurf/mcp_config.json

   {
     "mcpServers": {
       "obsidian": {
         "command": "uvx",
         "args": ["obsidian-mcp"],
         "env": {
           "OBSIDIAN_REST_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

   然後：打開 Windsurf 設置→高級設置→級聯→添加服務器→刷新。

   將 your-api-key-here 替換為你從 Obsidian 複製的 API 密鑰。

   ⚠️ 重要提示

   如果你使用 HTTPS 或自定義端口，請在 env 部分添加 "OBSIDIAN_API_URL": "https://localhost:27124"。詳情請參閱 高級配置。

3. 重啟你的 AI 工具 以加載新配置。

大功告成！現在你的 AI 工具可以訪問你的 Obsidian 知識庫了。

💡 使用建議

此安裝方式使用了 uvx，它會自動下載並在隔離環境中運行服務器。大多數用戶無需再安裝其他東西。如果你沒有安裝 uv，也可以使用 pipx install obsidian-mcp，並在配置中將命令改為 "obsidian-mcp"。

立即試用

以下是一些示例提示，助你快速上手：

• "顯示我本週修改過的所有筆記"
• "為今天創建一篇包含會議議程的日常筆記"
• "搜索所有關於項目規劃的筆記"
• "讀取我的 Ideas/startup.md 筆記"

開發安裝

1. 克隆倉庫：

git clone https://github.com/natestrong/obsidian-mcp
cd obsidian-mcp

2. 設置 Python 環境：

# 使用 pyenv（推薦）
pyenv virtualenv 3.12.9 obsidian-mcp
pyenv activate obsidian-mcp

# 或者使用 venv
python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

3. 安裝依賴項：

pip install -r requirements.txt

4. 設置 Obsidian Local REST API：
   • 在 Obsidian 中安裝 Local REST API 插件。
   • 在 Obsidian 設置中啟用該插件。
   • 從插件設置中複製 API 密鑰。
   • 記錄端口號（默認：HTTP 為 27123，HTTPS 為 27124）。
5. 配置環境變量：

export OBSIDIAN_REST_API_KEY="your-api-key-here"
# export OBSIDIAN_API_URL="https://localhost:27124"  # 可選：僅在使用 HTTPS 時設置

6. 添加到 Claude Desktop（用於開發）： 編輯你的 Claude Desktop 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "/path/to/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/obsidian-mcp",
      "env": {
        "PYTHONPATH": "/path/to/obsidian-mcp",
        "OBSIDIAN_REST_API_KEY": "your-api-key-here"
      }
    }
  }
}

✨ 主要特性

• 📖 讀寫筆記 - 可完全訪問你的 Obsidian 知識庫，並具備自動覆蓋保護功能。
• 🔍 智能搜索 - 可根據內容、標籤或修改日期查找筆記。
• 📁 瀏覽知識庫 - 按目錄列出並導航你的筆記和文件夾。
• 🏷️ 標籤管理 - 添加、刪除和組織標籤（支持前置元數據和內聯標籤）。
• 🔗 鏈接管理 - 查找反向鏈接、分析出站鏈接並識別斷鏈。
• 📊 筆記洞察 - 獲取諸如字數統計和鏈接分析等統計信息。
• 🎯 AI 優化 - 清晰的錯誤消息和智能默認設置，以實現更好的 AI 交互。
• 🔒 安全可靠 - 通過 API 密鑰認證，僅支持本地連接。
• ⚡ 性能優化 - 支持併發操作和批量處理，適用於大型知識庫。
• 🚀 批量操作 - 創建文件夾層次結構並移動整個文件夾及其所有內容。

📦 安裝指南

快速安裝

1. 安裝並配置 Obsidian：

   • 在 Obsidian 中安裝 Local REST API 插件。
   • 在“設置”>“社區插件”中啟用該插件。
   • 進入“設置”>“Local REST API”。
   • 複製你的 API 密鑰（在步驟 2 中會用到）。

2. 配置你的 AI 工具：

   Claude Desktop

   編輯你的 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "obsidian": {
         "command": "uvx",
         "args": ["obsidian-mcp"],
         "env": {
           "OBSIDIAN_REST_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

   Cursor IDE

   在你的 Cursor 設置中添加以下內容：

   • 項目特定設置：項目目錄下的 .cursor/mcp.json
   • 全局設置：主目錄下的 ~/.cursor/mcp.json

   {
     "mcpServers": {
       "obsidian": {
         "command": "uvx",
         "args": ["obsidian-mcp"],
         "env": {
           "OBSIDIAN_REST_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

   然後：打開“設置”→“Cursor 設置”→啟用 MCP。

   Windsurf IDE

   編輯你的 Windsurf 配置文件：

   • 位置：~/.codeium/windsurf/mcp_config.json

   {
     "mcpServers": {
       "obsidian": {
         "command": "uvx",
         "args": ["obsidian-mcp"],
         "env": {
           "OBSIDIAN_REST_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

   然後：打開 Windsurf 設置→高級設置→級聯→添加服務器→刷新。

   將 your-api-key-here 替換為你從 Obsidian 複製的 API 密鑰。

   ⚠️ 重要提示

   如果你使用 HTTPS 或自定義端口，請在 env 部分添加 "OBSIDIAN_API_URL": "https://localhost:27124"。詳情請參閱 高級配置。

3. 重啟你的 AI 工具 以加載新配置。

大功告成！現在你的 AI 工具可以訪問你的 Obsidian 知識庫了。

💡 使用建議

此安裝方式使用了 uvx，它會自動下載並在隔離環境中運行服務器。大多數用戶無需再安裝其他東西。如果你沒有安裝 uv，也可以使用 pipx install obsidian-mcp，並在配置中將命令改為 "obsidian-mcp"。

開發安裝

1. 克隆倉庫：

git clone https://github.com/natestrong/obsidian-mcp
cd obsidian-mcp

2. 設置 Python 環境：

# 使用 pyenv（推薦）
pyenv virtualenv 3.12.9 obsidian-mcp
pyenv activate obsidian-mcp

# 或者使用 venv
python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

3. 安裝依賴項：

pip install -r requirements.txt

4. 設置 Obsidian Local REST API：
   • 在 Obsidian 中安裝 Local REST API 插件。
   • 在 Obsidian 設置中啟用該插件。
   • 從插件設置中複製 API 密鑰。
   • 記錄端口號（默認：HTTP 為 27123，HTTPS 為 27124）。
5. 配置環境變量：

export OBSIDIAN_REST_API_KEY="your-api-key-here"
# export OBSIDIAN_API_URL="https://localhost:27124"  # 可選：僅在使用 HTTPS 時設置

6. 添加到 Claude Desktop（用於開發）： 編輯你的 Claude Desktop 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "/path/to/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/obsidian-mcp",
      "env": {
        "PYTHONPATH": "/path/to/obsidian-mcp",
        "OBSIDIAN_REST_API_KEY": "your-api-key-here"
      }
    }
  }
}

💻 使用示例

基礎用法

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

# 設置 Python 環境
# 使用 pyenv（推薦）
pyenv virtualenv 3.12.9 obsidian-mcp
pyenv activate obsidian-mcp

# 或者使用 venv
python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

# 安裝依賴項
pip install -r requirements.txt

# 設置 Obsidian Local REST API
# 在 Obsidian 中安裝 Local REST API 插件
# 在 Obsidian 設置中啟用該插件
# 從插件設置中複製 API 密鑰
# 記錄端口號（默認：HTTP 為 27123，HTTPS 為 27124）

# 配置環境變量
export OBSIDIAN_REST_API_KEY="your-api-key-here"
# export OBSIDIAN_API_URL="https://localhost:27124"  # 可選：僅在使用 HTTPS 時設置

# 添加到 Claude Desktop（用於開發）
# 編輯你的 Claude Desktop 配置文件：
# - macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
# - Windows：`%APPDATA%\Claude\claude_desktop_config.json`

# {
#   "mcpServers": {
#     "obsidian": {
#       "command": "/path/to/python",
#       "args": ["-m", "src.server"],
#       "cwd": "/path/to/obsidian-mcp",
#       "env": {
#         "PYTHONPATH": "/path/to/obsidian-mcp",
#         "OBSIDIAN_REST_API_KEY": "your-api-key-here"
#       }
#     }
#   }
# }

高級用法

# 運行測試
# 運行所有測試
python tests/run_tests.py

# 運行特定類型的測試
python tests/run_tests.py unit         # 單元測試（需要 pytest）
python tests/run_tests.py integration  # 集成測試（需要 pytest）
python tests/run_tests.py live         # 使用真實 Obsidian 進行實時測試

# 運行單個測試文件
python tests/test_comprehensive.py     # 完整工作流測試
python tests/test_data_validation.py   # 數據結構驗證

📚 詳細文檔

項目結構

obsidian-mcp/
├── src/
│   ├── server.py           # 主入口點，具有豐富的參數模式
│   ├── tools/              # 工具實現
│   │   ├── note_management.py    # CRUD 操作
│   │   ├── search_discovery.py   # 搜索和導航
│   │   ├── organization.py       # 標籤、移動、元數據
│   │   └── link_management.py    # 反向鏈接、出站鏈接、斷鏈
│   ├── models/             # 用於驗證的 Pydantic 模型
│   │   └── obsidian.py    # 筆記、搜索結果、知識庫項模型
│   ├── utils/              # 共享實用工具
│   │   ├── obsidian_api.py      # REST API 客戶端包裝器
│   │   ├── validators.py        # 路徑驗證、清理
│   │   └── validation.py        # 全面的參數驗證
│   └── constants.py       # API 端點、默認值、增強的錯誤消息
├── tests/
│   ├── run_tests.py       # 智能測試運行器
│   ├── test_unit.py       # 帶模擬的單元測試
│   ├── test_integration.py # 集成測試
│   ├── test_live.py       # 實時 API 測試
│   ├── test_comprehensive.py # 完整工作流驗證
│   └── test_data_validation.py # 返回值測試
├── docs/                  # 額外的文檔
├── requirements.txt       # Python 依賴項
├── CLAUDE.md             # Claude 代碼說明
└── README.md

可用工具

筆記管理

read_note

讀取特定筆記的內容和元數據。 參數：

• path：筆記的路徑（例如，"Daily/2024-01-15.md"） 返回值：

{
  "path": "Daily/2024-01-15.md",
  "content": "# 日常筆記\n\n這裡是內容...",
  "metadata": {
    "tags": ["daily", "journal"],
    "aliases": [],
    "frontmatter": {}
  }
}

create_note

創建新筆記或更新現有筆記。 參數：

• path：筆記的創建路徑
• content：筆記的 Markdown 內容（建議添加標籤以進行組織）
• overwrite（默認：false）：是否覆蓋現有筆記 最佳實踐：
• 創建筆記時添加相關標籤，以保持組織性。
• 使用 list_tags 查看現有標籤，以保持一致性。
• 標籤可以作為內聯哈希標籤（#tag）或前置元數據添加。

update_note

更新現有筆記的內容。 ⚠️ 重要提示：默認情況下，此工具會替換整個筆記內容。如果需要保留現有內容，請先讀取筆記。 參數：

• path：要更新的筆記路徑
• content：新的 Markdown 內容（除非使用追加模式，否則將替換現有內容）
• create_if_not_exists（默認：false）：如果筆記不存在則創建
• merge_strategy（默認："replace"）：處理內容的方式
  • "replace"：覆蓋整個筆記內容（默認）
  • "append"：將新內容添加到現有內容的末尾 安全更新模式：

1. 始終先讀取以保留內容。
2. 根據需要修改內容。
3. 使用完整的新內容進行更新。
4. 或者使用追加模式將內容添加到末尾。

delete_note

從知識庫中刪除筆記。 參數：

• path：要刪除的筆記路徑

搜索和發現

search_notes

搜索包含特定文本或標籤的筆記。 參數：

• query：搜索查詢（支持 Obsidian 搜索語法）
• context_length（默認：100）：匹配項周圍顯示的字符數 搜索語法：
• 文本搜索："機器學習"
• 標籤搜索：tag:project 或 tag:#project
• 路徑搜索：path:Daily/
• 組合搜索：tag:urgent TODO

search_by_date

按創建或修改日期搜索筆記。 參數：

• date_type（默認："modified"）：可以是 "created" 或 "modified"
• days_ago（默認：7）：回顧的天數
• operator（默認："within"）：可以是 "within"（過去 N 天）或 "exactly"（正好 N 天前） 返回值：

{
  "query": "過去 7 天內修改的筆記",
  "count": 15,
  "results": [
    {
      "path": "Daily/2024-01-15.md",
      "date": "2024-01-15T10:30:00",
      "days_ago": 1
    }
  ]
}

示例用法：

• "顯示我今天修改的所有筆記" → search_by_date("modified", 0, "within")
• "顯示我本週修改的所有筆記" → search_by_date("modified", 7, "within")
• "查找過去 30 天內創建的筆記" → search_by_date("created", 30, "within")
• "哪些筆記正好在 2 天前被修改了？" → search_by_date("modified", 2, "exactly")

list_notes

列出知識庫中的筆記，可選擇遞歸遍歷。 參數：

• directory（可選）：要列出的特定目錄（例如，"Daily"，"Projects"）
• recursive（默認：true）：遞歸列出所有筆記 返回值：

{
  "directory": "Daily",
  "recursive": true,
  "count": 365,
  "notes": [
    {"path": "Daily/2024-01-01.md", "name": "2024-01-01.md"},
    {"path": "Daily/2024-01-02.md", "name": "2024-01-02.md"}
  ]
}

list_folders

列出知識庫中的文件夾，可選擇遞歸遍歷。 參數：

• directory（可選）：要列出的特定目錄
• recursive（默認：true）：包括所有嵌套子文件夾 返回值：

{
  "directory": "Projects",
  "recursive": true,
  "count": 12,
  "folders": [
    {"path": "Projects/Active", "name": "Active"},
    {"path": "Projects/Archive", "name": "Archive"},
    {"path": "Projects/Ideas", "name": "Ideas"}
  ]
}

組織管理

create_folder

在知識庫中創建新文件夾，包括路徑中的所有父文件夾。 參數：

• folder_path：要創建的文件夾路徑（例如，"Apple/Studies/J71P"）
• create_placeholder（默認：true）：是否創建佔位符文件 返回值：

{
  "folder": "Apple/Studies/J71P",
  "created": true,
  "placeholder_file": "Apple/Studies/J71P/.gitkeep",
  "folders_created": ["Apple", "Apple/Studies", "Apple/Studies/J71P"]
}

注意：此工具將創建所有必要的父文件夾。例如，如果 "Apple" 存在但 "Studies" 不存在，它將創建 "Studies" 和 "J71P"。

move_note

將筆記移動到新位置。 參數：

• source_path：筆記的當前路徑
• destination_path：筆記的新路徑
• update_links（默認：true）：更新其他筆記中的鏈接（未來增強功能）

move_folder

將整個文件夾及其所有內容移動到新位置。 參數：

• source_folder：當前文件夾路徑（例如，"Projects/Old"）
• destination_folder：新文件夾路徑（例如，"Archive/Projects/Old"）
• update_links（默認：true）：更新其他筆記中的鏈接（未來增強功能） 返回值：

{
  "source": "Projects/Completed",
  "destination": "Archive/2024/Projects",
  "moved": true,
  "notes_moved": 15,
  "folders_moved": 3,
  "links_updated": 0
}

add_tags

向筆記的前置元數據中添加標籤。 參數：

• path：筆記的路徑
• tags：要添加的標籤列表（不帶 # 前綴）

update_tags

更新筆記上的標籤 - 可以替換所有標籤或與現有標籤合併。 參數：

• path：筆記的路徑
• tags：要設置的新標籤（不帶 # 前綴）
• merge（默認：false）：如果為 true，則添加到現有標籤；如果為 false，則替換所有標籤 非常適合 AI 工作流：

用戶："告訴我這篇筆記是關於什麼的，並添加適當的標籤"
AI：[讀取筆記] "這篇筆記是關於機器學習研究的..."
AI：[使用 update_tags 設置標籤：["ai", "research", "neural-networks"]]

remove_tags

從筆記的前置元數據中刪除標籤。 參數：

• path：筆記的路徑
• tags：要刪除的標籤列表

get_note_info

獲取筆記的元數據和統計信息，而無需檢索其完整內容。 參數：

• path：筆記的路徑 返回值：

{
  "path": "Projects/AI Research.md",
  "exists": true,
  "metadata": {
    "tags": ["ai", "research"],
    "aliases": [],
    "frontmatter": {}
  },
  "stats": {
    "size_bytes": 4523,
    "word_count": 823,
    "link_count": 12
  }
}

list_tags

列出知識庫中使用的所有唯一標籤及其使用統計信息。 參數：

• include_counts（默認：true）：包括每個標籤的使用計數
• sort_by（默認："name"）：按 "name" 或 "count" 排序 返回值：

{
  "total_tags": 25,
  "tags": [
    {"name": "project", "count": 42},
    {"name": "meeting", "count": 38},
    {"name": "idea", "count": 15}
  ]
}

性能說明：

• 對於小型知識庫（<1000 篇筆記）速度較快。
• 對於大型知識庫可能需要幾秒鐘。
• 使用併發批處理進行優化。

鏈接管理

⚡ 性能說明：鏈接管理工具在 v1.1.5 中進行了重大優化：

• 鏈接有效性檢查速度提高了 84 倍。
• 斷鏈檢測速度提高了 96 倍。
• 反向鏈接搜索速度提高了 2 倍。
• 包括自動緩存和批處理。

get_backlinks

查找所有鏈接到特定筆記的筆記。 參數：

• path：要查找反向鏈接的筆記路徑
• include_context（默認：true）：是否包括鏈接周圍的文本上下文
• context_length（默認：100）：要包括的上下文的字符數 返回值：

{
  "target_note": "Projects/AI Research.md",
  "backlink_count": 5,
  "backlinks": [
    {
      "source_path": "Daily/2024-01-15.md",
      "link_text": "AI 研究",
      "link_type": "wiki",
      "context": "...今天正在進行 [[AI 研究]] 項目..."
    }
  ]
}

使用場景：

• 瞭解哪些筆記引用了某個概念或主題。
• 發現筆記之間的關係。
• 構建筆記連接的心理地圖。

get_outgoing_links

列出特定筆記中的所有鏈接。 參數：

• path：要提取鏈接的筆記路徑
• check_validity（默認：false）：是否檢查鏈接的筆記是否存在 返回值：

{
  "source_note": "Projects/Overview.md",
  "link_count": 8,
  "links": [
    {
      "path": "Projects/AI Research.md",
      "display_text": "AI 研究",
      "type": "wiki",
      "exists": true
    }
  ]
}

使用場景：

• 瞭解筆記引用的內容。
• 在移動/刪除筆記之前檢查筆記依賴項。
• 探索索引或中心筆記的結構。

find_broken_links

查找知識庫、特定目錄或單個筆記中的所有斷鏈。 參數：

• directory（可選）：要檢查的特定目錄（默認為整個知識庫）
• single_note（可選）：僅檢查此特定筆記中的斷鏈 返回值：

{
  "directory": "/",
  "broken_link_count": 3,
  "affected_notes": 2,
  "broken_links": [
    {
      "source_path": "Projects/Overview.md",
      "broken_link": "Projects/Old Name.md",
      "link_text": "舊項目",
      "link_type": "wiki"
    }
  ]
}

使用場景：

• 重命名或刪除筆記後。
• 定期進行知識庫維護。
• 重組文件夾結構之前。

🔧 技術細節

運行測試

# 運行所有測試
python tests/run_tests.py

# 運行特定類型的測試
python tests/run_tests.py unit         # 單元測試（需要 pytest）
python tests/run_tests.py integration  # 集成測試（需要 pytest）
python tests/run_tests.py live         # 使用真實 Obsidian 進行實時測試

# 運行單個測試文件
python tests/test_comprehensive.py     # 完整工作流測試
python tests/test_data_validation.py   # 數據結構驗證

使用 MCP Inspector 進行測試

1. 確保 Obsidian 正在運行，並且 Local REST API 插件已啟用。
2. 運行 MCP Inspector：

npx @modelcontextprotocol/inspector python -m src.server

3. 打開 Inspector UI：在 http://localhost:5173 打開。
4. 交互式測試工具：使用你實際的知識庫進行測試。

與 Claude Desktop 集成

有關開發安裝，請參閱上面的 開發安裝 部分。

增強的錯誤處理

服務器提供詳細、可操作的錯誤消息，以幫助 AI 系統從錯誤中恢復。

示例錯誤消息

無效路徑：

無效的筆記路徑：'../../../etc/passwd'。
有效路徑必須：1) 以 .md 或 .markdown 結尾；2) 使用正斜槓（例如，'folder/note.md'）；
3) 不包含 '..' 或不以 '/' 開頭；4) 不超過 255 個字符。
示例：'Daily/2024-01-15.md' 或 'Projects/My Project.md'

空搜索查詢：

搜索查詢不能為空。
有效查詢：1) 關鍵字：'機器學習'；
2) 標籤：'tag:#project'；3) 路徑：'path:Daily/'；
4) 組合：'tag:#urgent TODO'

無效日期參數：

無效的 date_type：'invalid'。
必須是 'created' 或 'modified'。
使用 'created' 按創建日期查找筆記，使用 'modified' 按最後編輯日期查找筆記。

故障排除

"連接被拒絕" 錯誤

• 確保 Obsidian 正在運行。
• 驗證 Local REST API 插件已啟用。
• 檢查端口是否匹配（默認：HTTP 為 27123，HTTPS 為 27124）。
• 確認 API 密鑰正確。
• 增強的錯誤消息將顯示正在使用的精確 URL 和端口。

標籤未顯示

• 確保標籤格式正確（帶或不帶 # 前綴）。
• 檢查 Local REST API 插件是否為最新版本。
• 前置元數據中的標籤應採用 YAML 數組格式：tags: [tag1, tag2]。
• 內聯標籤應使用 # 前綴：#project #urgent。

"證書驗證失敗" 錯誤

• 這是 Local REST API 的自簽名證書的預期情況。
• 服務器會自動處理此問題。

"模塊未找到" 錯誤

• 確保你的虛擬環境已激活。
• 從項目根目錄運行：python -m src.server。
• 驗證 PYTHONPATH 包含項目目錄。

列出筆記時結果為空

• 使用 list_notes 時指定目錄（例如，"Daily"，"Projects"）。
• 根目錄列表需要遞歸實現。
• 檢查筆記是否在子目錄中。

標籤未更新

• 確保筆記有 YAML 前置元數據部分以使用前置元數據標籤。
• 前置元數據必須包含 tags: 字段（即使為空）。
• 服務器現在可以正確讀取前置元數據標籤和內聯哈希標籤。

AI 助手的最佳實踐

防止數據丟失

1. 更新前始終先讀取：默認情況下，update_note 工具會替換內容。
2. 使用追加模式進行添加：向現有筆記添加內容時，使用 merge_strategy="append"。
3. 檢查筆記是否存在：在修改之前使用 read_note 驗證筆記是否存在。
4. 明確覆蓋操作：僅在有意替換內容時使用 overwrite=true。

推薦工作流

安全的筆記編輯：

1. 首先讀取現有筆記。
2. 根據需要修改內容。
3. 使用完整的新內容進行更新。

添加到日常筆記：

• 使用 merge_strategy="append" 添加條目，而不會丟失現有內容。

創建新筆記：

• 使用 create_note 並將 overwrite=false（默認）以防止意外覆蓋。
• 添加相關標籤以保持組織性。
• 使用 list_tags 查看現有標籤，避免創建重複標籤。

使用標籤進行組織：

• 在創建新標籤之前，使用 list_tags 檢查現有標籤。
• 保持一致的命名（例如，使用 "project" 而不是 "projects"）。
• 使用標籤實現強大的搜索和過濾功能。

安全考慮

• 保密你的 API 密鑰 - 切勿將其提交到版本控制中。
• 服務器驗證所有路徑，以防止目錄遍歷攻擊。
• 與 Obsidian 的通信默認使用 HTTP（僅本地連接）或使用自簽名證書的 HTTPS。
• 服務器僅通過 REST API 接受本地連接。

開發

代碼風格

• 使用 FastMCP 框架實現 MCP。
• 使用 Pydantic 模型進行類型安全和驗證。
• 採用模塊化架構，職責分離。
• 全面的錯誤處理和用戶友好的消息。

添加新工具

1. 在 src/tools/ 下的適當模塊中創建工具函數。
2. 如果需要，在 src/models/ 中添加 Pydantic 模型。
3. 使用 @mcp.tool() 裝飾器在 src/server.py 中註冊工具。
4. 包含全面的文檔字符串。
5. 在 tests/ 中添加測試。
6. 在部署之前使用 MCP Inspector 進行測試。

變更日誌

v1.1.7 (2025-01-10)

• 🔄 將默認 API 端點更改為 HTTP (http://127.0.0.1:27123)，以便於設置。
• 📝 更新文檔，以反映 HTTP 為默認設置，HTTPS 為可選設置。
• 🔧 添加關於 URL 中自動處理尾隨斜槓的說明。
• ✨ 改進首次用戶體驗，實現零配置設置。

v1.1.6 (2025-01-10)

• 🐛 修復創建或更新大型筆記時的超時錯誤。
• ⚡ 添加優雅的超時處理，以提高大型內容的可靠性。
• 🔧 改進錯誤報告，以防止成功操作時出現誤報失敗。

v1.1.5 (2025-01-09)

• ⚡ 對鏈接管理進行大規模性能優化：
  • 鏈接有效性檢查速度提高 84 倍。
  • 斷鏈檢測速度提高 96 倍。
  • 反向鏈接搜索速度提高 2 倍。
  • 添加自動緩存和批處理。
• 🔧 優化大型知識庫的併發操作。
• 📝 增強關於性能考慮的文檔。

v1.1.4 (2025-01-09)

• 🔗 添加鏈接管理工具，以進行全面的知識庫分析：
  • get_backlinks - 查找所有鏈接到特定筆記的筆記。
  • get_outgoing_links - 列出筆記中的所有鏈接，並檢查其有效性。
  • find_broken_links - 識別斷鏈，以進行知識庫維護。
• 🔧 修復 URL 構造，以支持 HTTPS（默認）和 HTTP 端點。
• 📝 增強鏈接解析，以處理 wiki 風格和 Markdown 鏈接。
• ⚡ 優化反向鏈接搜索，以處理各種路徑格式。

v1.1.3 (2025-01-09)

• 🐛 修復 search_by_date 以正確查找今天修改的筆記（days_ago=0）。
• ✨ 添加 list_folders 工具，用於探索知識庫文件夾結構。
• ✨ 添加 create_folder 工具，用於創建完整的文件夾層次結構。
• ✨ 添加 move_folder 工具，用於批量文件夾操作。
• ✨ 添加 update_tags 工具，用於 AI 驅動的標籤管理。
• 🐛 修復標籤讀取，以正確處理前置元數據和內聯哈希標籤。
• ✨ 添加 list_tags 工具，用於發現現有標籤及其使用統計信息。
• ⚡ 通過併發批處理優化大型知識庫的性能。
• 📝 遵循 MCP 最佳實踐，改進文檔和錯誤消息。
• 🎯 增強 create_note 以鼓勵使用標籤，以實現更好的組織。

v1.1.2 (2025-01-09)

• 修復 PyPI 包文檔。

v1.1.1 (2025-01-06)

• 首次 PyPI 發佈。

發佈（維護者適用）

要將新版本發佈到 PyPI，請執行以下操作：

# 1. 在 pyproject.toml 中更新版本號
# 2. 清理舊構建
rm -rf dist/ build/ *.egg-info/

# 3. 構建包
python -m build

# 4. 檢查包
twine check dist/*

# 5. 上傳到 PyPI
twine upload dist/* -u __token__ -p $PYPI_API_KEY

# 6. 創建並推送 git 標籤
git tag -a v1.1.7 -m "發佈版本 1.1.7"
git push origin v1.1.7

用戶可以使用以下命令進行安裝和運行：

# 使用 uvx（推薦 - 無需安裝）
uvx obsidian-mcp

# 或者使用 pipx 全局安裝
pipx install obsidian-mcp
obsidian-mcp

# 或者使用 pip 安裝
pip install obsidian-mcp
obsidian-mcp

配置

高級配置

如果你使用非標準設置，可以使用以下環境變量自定義服務器行為：

• OBSIDIAN_API_URL - 覆蓋默認的 API 端點（默認：http://127.0.0.1:27123）
  • 如果你運行的是 HTTPS 端點（例如，https://localhost:27124），請使用此選項。
  • 或者如果你在 Local REST API 插件設置中更改了端口號。
  • 默認使用 HTTP 端點，以便於設置。
  • 注意：尾隨斜槓會自動處理（http://127.0.0.1:27123 和 http://127.0.0.1:27123/ 都可以）。

HTTPS 或非標準配置示例

{
  "mcpServers": {
    "obsidian": {
      "command": "uvx",
      "args": ["obsidian-mcp"],
      "env": {
        "OBSIDIAN_REST_API_KEY": "your-api-key-here",
        "OBSIDIAN_API_URL": "https://localhost:27124"
      }
    }
  }
}

貢獻

1. 分叉倉庫。
2. 創建功能分支（git checkout -b feature/amazing-tool）。
3. 為新功能編寫測試。
4. 確保所有測試通過。
5. 提交更改（git commit -m '添加出色的工具'）。
6. 推送到分支（git push origin feature/amazing-tool）。
7. 打開拉取請求。

📄 許可證

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

致謝

• Anthropic 創建了模型上下文協議。
• Obsidian 團隊開發了出色的筆記應用。
• coddingtonbear 開發了 Local REST API 插件。
• dsp-ant 開發了 FastMCP 框架。