Obsidian Local Rest Api MCP

🚀 Obsidian Local REST API MCP 服務器

這是一個基於 AI 原生的 MCP（模型上下文協議）服務器，可通過本地 REST API 提供智能、面向任務的工具，用於與 Obsidian 保險庫進行交互。

🚀 快速開始

本 MCP 服務器按照 AI 原生原則進行了重新設計，而非簡單的 API 到工具映射。它不提供低級的 CRUD 操作，而是提供大語言模型（LLMs）能更有效推理的高級、面向任務的工具。

前後對比：轉變之處

✨ 主要特性

可用工具

目錄和文件操作

list_directory

目的：通過分頁列出目錄內容，防止上下文溢出

{
  "path": "Projects/",
  "recursive": false,
  "limit": 20,
  "offset": 0
}

對 AI 的好處：大語言模型可以逐步探索保險庫結構，而不會使上下文過載

read_file

目的：讀取保險庫中任何文件的內容

{"path": "notes/meeting-notes.md"}

write_file

目的：以多種模式寫入文件，取代了單獨的創建/更新操作

{
  "path": "notes/summary.md",
  "content": "# Meeting Summary\n...",
  "mode": "append"  // "overwrite", "append", "prepend"
}

對 AI 的好處：單個工具處理所有寫入場景，消除歧義

delete_item

目的：刪除任何文件或目錄

{"path": "old-notes/"}

AI 原生筆記操作

create_or_update_note

目的：智能更新插入操作，若筆記不存在則創建，若存在則更新

{
  "path": "daily/2024-12-26",
  "content": "## Tasks\n- Review AI-native MCP design",
  "frontmatter": {"tags": ["daily", "tasks"]}
}

對 AI 的好處：消除了“此筆記是否存在”的決策樹

get_daily_note

目的：通過常見命名模式智能檢索每日筆記

{"date": "today"}  // 或 "yesterday", "2024-12-26"

對 AI 的好處：抽象出文件系統細節和命名約定

get_recent_notes

目的：獲取最近修改的筆記

{"limit": 5}

對 AI 的好處：符合自然的“我最近處理了哪些內容”的查詢

高級搜索與發現

search_vault

目的：具有高級過濾功能的多範圍搜索

{
  "query": "machine learning",
  "scope": ["content", "filename", "tags"],
  "path_filter": "research/"
}

對 AI 的好處：精確、有針對性的搜索減少噪音

find_related_notes

目的：發現筆記之間的概念關係

{
  "path": "ai-research.md",
  "on": ["tags", "links"]
}

對 AI 的好處：支持基於關係的工作流程和意外發現

舊版工具（向後兼容）

服務器保持與現有工具（如 get_note、list_notes、get_metadata_keys 等）的向後兼容性。

📦 安裝指南

前提條件

• Node.js 18+ 或 Bun 運行時
• Obsidian Local REST API 在本地運行（默認：http://obsidian-local-rest-api.test）

使用 npx（推薦）

npx obsidian-local-rest-api-mcp

從源代碼安裝

# 克隆倉庫
git clone https://github.com/j-shelfwood/obsidian-local-rest-api-mcp.git
cd obsidian-local-rest-api-mcp

# 使用 bun 安裝依賴
bun install

# 構建項目
bun run build

📚 詳細文檔

配置

設置用於 API 連接的環境變量：

export OBSIDIAN_API_URL="http://obsidian-local-rest-api.test"  # 默認 URL（對於非 Valet 設置為 http://localhost:8000）
export OBSIDIAN_API_KEY="your-api-key"          # 可選的令牌

使用方法

運行服務器

# 開發模式，支持自動重新加載
bun run dev

# 生產模式
bun run start

# 或者直接運行
node build/index.js

MCP 客戶端配置

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "npx",
      "args": ["obsidian-local-rest-api-mcp"],
      "env": {
        "OBSIDIAN_API_URL": "http://obsidian-local-rest-api.test",
        "OBSIDIAN_API_KEY": "your-api-key-if-needed"
      }
    }
  }
}

帶有 MCP 擴展的 VS Code

使用包含的 .vscode/mcp.json 配置文件。

開發

# 開發模式下的監聽模式
bun run dev

# 構建 TypeScript
bun run build

# 類型檢查
bun run tsc --noEmit

架構

• ObsidianApiClient - REST API 端點的 HTTP 客戶端包裝器
• ObsidianMcpServer - 帶有工具處理程序的 MCP 服務器實現
• Configuration - 基於環境的配置，帶有驗證功能

錯誤處理

服務器包含全面的錯誤處理：

• API 連接失敗
• 無效的工具參數
• 網絡超時
• 身份驗證錯誤 錯誤以帶有描述性消息的 MCP 工具調用響應形式返回。

調試

通過設置環境變量啟用調試日誌：

export DEBUG=1
export NODE_ENV=development

服務器日誌寫入 stderr，以避免干擾標準輸出上的 MCP 協議通信。

故障排除

MCP 服務器啟動失敗

如果你的 MCP 客戶端顯示“啟動失敗”或類似錯誤：

1. 直接測試服務器：

npx obsidian-local-rest-api-mcp --version

應輸出版本號。 2. 測試 MCP 協議：

# 運行測試腳本
node -e "
const { spawn } = require('child_process');
const child = spawn('npx', ['obsidian-local-rest-api-mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
child.stdout.on('data', d => console.log('OUT:', d.toString()));
child.stderr.on('data', d => console.log('ERR:', d.toString()));
setTimeout(() => {
  child.stdin.write(JSON.stringify({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2024-11-05',capabilities:{},clientInfo:{name:'test',version:'1.0.0'}}})+'\n');
  setTimeout(() => child.kill(), 2000);
}, 500);
"

應顯示初始化響應。 3. 檢查環境變量：

• 確保 OBSIDIAN_API_URL 指向正在運行的 Obsidian Local REST API
• 直接測試 API：curl http://obsidian-local-rest-api.test/api/files（或你配置的 API URL）

4. 驗證 Obsidian Local REST API：

• 安裝並運行 Obsidian Local REST API
• 確認它在配置的端口上可訪問
• 檢查是否需要身份驗證

常見問題

• “命令未找到”：確保已安裝 Node.js/npm 並可使用 npx
• “連接被拒絕”：Obsidian Local REST API 未運行或 URL 錯誤
• Laravel Valet .test 域名：如果使用 Laravel Valet，確保你的項目目錄名稱與 .test 域名匹配（例如，對於 /obsidian-local-rest-api/ 中的項目，使用 obsidian-local-rest-api.test）
• “未授權”：檢查是否需要 API 密鑰並正確配置
• “超時”：增加客戶端配置中的超時時間或檢查網絡連接

Cherry Studio 配置

對於 Cherry Studio，請使用以下確切設置：

• 名稱：obsidian-vault（或你喜歡的任何名稱）
• 類型：標準輸入/輸出 (stdio)
• 命令：npx
• 參數：obsidian-local-rest-api-mcp
• 環境變量：
  • OBSIDIAN_API_URL：你的 API URL（例如，對於 Laravel Valet，使用 http://obsidian-local-rest-api.test）
  • OBSIDIAN_API_KEY：如果需要身份驗證，可選的 API 密鑰

貢獻

1. 分叉倉庫
2. 創建功能分支
3. 使用正確的 TypeScript 類型進行更改
4. 使用你的 Obsidian 保險庫進行測試
5. 提交拉取請求

📄 許可證

本項目採用 MIT 許可證。