Obsidian Ts MCP

🚀 obsidian-ts-mcp

這是一個模型上下文協議（MCP）服務器，它封裝了官方的 Obsidian CLI，允許 VS Code（以及其他任何 MCP 客戶端）中的 AI 代理讀取、寫入、搜索和管理 Obsidian 保險庫中的筆記。

🚀 快速開始

在使用此 MCP 服務器前，你需要滿足以下先決條件：

使用 MCP 服務器時，Obsidian 桌面應用必須處於運行狀態，並且 obsidian 二進制文件必須在你的 PATH 中可用。

📦 安裝指南

git clone https://github.com/dickiedyce/obsidian-ts-mcp.git
cd obsidian-ts-mcp
npm install
npm run build

📚 詳細文檔

VS Code（用戶級 MCP）

將以下內容添加到你的 VS Code MCP 配置中：

{
  "servers": {
    "obsidian": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/obsidian-ts-mcp/dist/server.js"],
      "env": {
        "OBSIDIAN_VAULT": "My Vault"
      }
    }
  }
}

Claude Desktop

將以下內容添加到 claude_desktop_config.json 中（在 macOS 上路徑為 ~/Library/Application Support/Claude/claude_desktop_config.json，在 Windows 上路徑為 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-ts-mcp/dist/server.js"],
      "env": {
        "OBSIDIAN_VAULT": "My Vault"
      }
    }
  }
}

將 OBSIDIAN_VAULT 設置為你要使用的保險庫名稱，該名稱必須與 Obsidian 保險庫切換器中顯示的名稱完全一致。

環境變量

可用工具

服務器提供了 37 個工具，分為十一個組。

核心 - 筆記管理

發現和上下文

屬性和元數據

任務

每日筆記（擴展）

模板

鏈接

屬性（擴展）

標籤（擴展）

文件管理

數據庫

項目管理

項目結構

src/
  cli.ts          -- 底層 Obsidian CLI 包裝器（執行、參數構建、錯誤處理）。
  fs-ops.ts       -- 直接的文件系統操作（創建目錄、讀取、寫入），用於精確的路徑控制。
  tools.ts        -- MCP 工具定義（名稱、描述、JSON 模式）。
  handlers.ts     -- 將工具調用（37 個工具）分派到 CLI 命令或文件系統操作。
  server.ts       -- MCP 服務器入口點（標準輸入輸出傳輸、錯誤處理）。
  validation.ts   -- 根據工具模式進行輸入驗證。
tests/
  cli.test.ts           -- 參數構建和錯誤類型的單元測試。
  fs-ops.test.ts        -- 文件系統操作的單元測試。
  runObsidian.test.ts   -- CLI 執行、超時、保險庫目標的測試。
  handlers.test.ts      -- 所有 37 個工具處理程序的測試（CLI 和文件系統操作被模擬）。
  tools.test.ts         -- 每個工具定義的模式驗證。
  validation.test.ts    -- 輸入驗證測試（類型、枚舉、必填字段）。
  server.test.ts        -- 服務器工廠、錯誤格式化、版本檢查。

開發

npm run dev           # 監聽模式下的 TypeScript 編譯
npm test              # 運行一次測試套件
npm run test:watch    # 在監聽模式下運行測試
npm run test:coverage # 運行測試並生成覆蓋率報告
npm run build         # 一次性編譯
npm run lint          # 運行 ESLint
npm run format:check  # 檢查 Prettier 格式化
npm start             # 在標準輸入輸出上啟動 MCP 服務器

工作原理

1. MCP 客戶端（VS Code、Claude Desktop 等）通過標準輸入輸出啟動服務器。
2. 客戶端調用 tools/list 並從 src/tools.ts 接收 37 個工具定義。
3. 當客戶端調用工具時，src/server.ts 將調用路由到 src/handlers.ts 中的 handleTool()。
4. handleTool() 根據工具模式驗證輸入，然後使用 src/cli.ts 中的 buildArgs() 和 runObsidian() 執行相應的 obsidian CLI 命令，或者在需要精確路徑控制時（例如在子目錄中創建筆記、項目管理）使用 src/fs-ops.ts 中的直接文件系統操作。
5. CLI 輸出作為文本內容塊返回給客戶端。

測試

測試使用 Vitest 並模擬 CLI 層，因此它們永遠不會調用真正的 Obsidian 二進制文件。運行以下命令進行測試：

npm test

安全考慮

• 完全保險庫訪問：服務器對目標保險庫中的每個筆記都有讀寫訪問權限。請將 OBSIDIAN_VAULT 限制為你願意向 AI 代理公開的保險庫。
• 無身份驗證：標準輸入輸出傳輸沒有內置的身份驗證。訪問控制完全取決於誰可以啟動服務器進程。
• 輸入驗證：所有工具輸入在執行前都會根據其聲明的模式進行驗證。服務器使用 execFile（而不是 exec）來避免 shell 注入，但請注意，文件/路徑值會直接傳遞給 Obsidian CLI。
• 環境繼承：子進程會繼承父進程的環境變量。避免在服務器進程可見的環境變量中存儲機密信息。

故障排除

📄 許可證

MIT