内容
# 終極 Obsidian MCP
一個 Model Context Protocol（MCP）伺服器，透過 [Obsidian 本地 REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) 外掛程式，為 Claude Code 提供對 Obsidian 資料庫的完整讀寫存取權。
為 Claude Code CLI（v2.x）構建。包含 17 個工具，涵蓋資料庫導航、筆記 CRUD、全文搜尋、前端資料管理、定期筆記和會話記憶體索引。
---
## 必要條件
- **Obsidian**，並啟用 [本地 REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) 外掛程式
- **Node.js** v18+（建議 v20）
- **Claude Code CLI** v2.x（`claude --version`）
---
## 安裝
### 1. 安裝 Obsidian 本地 REST API 外掛程式
在 Obsidian 中：設定 → 社群外掛程式 → 瀏覽 → 搜尋 "本地 REST API" → 安裝 → 啟用。
從外掛程式設定中複製 API 金鑰。預設端點是 `http://127.0.0.1:27123`。
### 2. 克隆並構建
```bash
git clone https://github.com/arturgomes/ultimate-obsidian-mcp.git
cd ultimate-obsidian-mcp
npm install
npm run build
```
驗證構建：
```bash
ls dist/
# client.js index.js sqlite.js tools.js ...
```
### 3. 在 Claude Code CLI 中註冊
> **重要**: Claude Code CLI 從 `~/.claude.json` 讀取 MCP 設定，而不是從 `~/.claude/settings.json`。請始終使用 `claude mcp add` 註冊伺服器。
```bash
claude mcp add-json -s user ultimate-obsidian '{
"type": "stdio",
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/ultimate-obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_API_KEY": "your-api-key-here",
"OBSIDIAN_BASE_URL": "http://127.0.0.1:27123"
}
}'
```
替換佔位符：
| 佔位符 | 如何找到 |
|---|---|
| `/absolute/path/to/node` | `which node` |
| `/absolute/path/to/ultimate-obsidian-mcp/dist/index.js` | 克隆儲存庫的完整路徑 |
| `your-api-key-here` | Obsidian → 設定 → 本地 REST API → API 金鑰 |
**使用絕對路徑** — Claude Code 在限制環境中啟動 MCP，其中 `$PATH` 可能不包含 NVM 或 Homebrew 路徑。
NVM 使用者範例：
```bash
claude mcp add-json -s user ultimate-obsidian '{
"type": "stdio",
"command": "/Users/yourname/.nvm/versions/node/v20.20.0/bin/node",
"args": ["/Users/yourname/projects/ultimate-obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_API_KEY": "your-api-key-here",
"OBSIDIAN_BASE_URL": "http://127.0.0.1:27123"
}
}'
```
### 4. 驗證
```bash
claude mcp get ultimate-obsidian
# ultimate-obsidian:
# 範圍：使用者設定（在所有專案中可用）
# 狀態：✓ 已連線
```
開始新的 Claude Code 會話。工具將在遞延工具清單中顯示為 `mcp__ultimate-obsidian__*`。
要確認伺服器正確啟動，請在第一次新會話後檢查日誌檔案：
```
! cat ~/Library/Logs/Claude/mcp-server-ultimate-obsidian.log
# [ultimate-obsidian-mcp] 啟動 — baseUrl=http://127.0.0.1:27123
```
---
## 冒煙測試
在註冊前，模擬 Claude Code 的限制啟動環境：
```bash
bash scripts/test-mcp.sh
# 啟動日誌（stderr）：
# [ultimate-obsidian-mcp] 啟動 — baseUrl=http://127.0.0.1:27123
#
# 已註冊工具：17
# ✅ MCP 伺服器正常 — 已註冊 17 個工具
#
# 測試 check_health 工具...
# 健康檢查結果：Obsidian REST API 可連線 ✅
```
編輯 `scripts/test-mcp.sh` 頂部的 `NODE`、`DIST`、`API_KEY` 和 `BASE_URL` 變數，以符合您的路徑。
---
## 工具
### 資料庫導航
| 工具 | 描述 |
|---|---|
| `list_vault` | 列出資料庫目錄中的檔案（省略路徑為根目錄） |
| `get_vault_info` | Obsidian REST API 伺服器資訊和資料庫名稱 |
| `get_periodic_note` | 獲取目前每日 / 每週 / 每月 / 每季度 / 每年筆記 |
### 筆記讀取
| 工具 | 描述 |
|---|---|
| `read_note` | 讀取資料庫筆記的完整內容 |
| `read_batch` | 一次讀取多個筆記 |
| `check_exists` | 檢查檔案是否存在 — 返回 `true` / `false`，在 404 時不會丟擲 |
| `grep_note` | 返回與 1 為基礎的行號的模式相符的行 |
### 筆記寫入
| 工具 | 描述 |
|---|---|
| `create_or_update_note` | 建立或更新筆記（`append` / `prepend` / `overwrite`） |
| `patch_note` | 在特定標題、區塊、前端資料鍵或檔案結尾進行修補 |
| `delete_note` | 刪除資料庫筆記 |
| `move_note` | 將筆記移動（重新命名 / 歸檔）到新路徑 |
| `search_replace_in_note` | 在筆記中查找和替換（字串或正則表達式） |
### 搜尋
| 工具 | 描述 |
|---|---|
| `search_vault` | 透過 Obsidian 搜尋整個資料庫 |
| `manage_frontmatter` | 獲取、設定或刪除單一 YAML 前端資料鍵 |
### 會話記憶體（SQLite FTS5）
這些工具支援 [codebase-intelligence](https://github.com/arturgomes/codebase-intelligence) Claude Code 外掛程式的跨會話記憶體系統。
| 工具 | 描述 |
|---|---|
| `index_note` | 將資料庫會話檔案索引到 SQLite FTS5 並更新其 `keywords:` 前端資料 |
| `search_sessions` | 對所有索引的會話檔案進行 BM25 全文搜尋 |
### 診斷
| 工具 | 描述 |
|---|---|
| `check_health` | 驗證 Obsidian REST API 連線 — 返回伺服器版本和認證狀態 |
---
## 環境變數
| 變數 | 預設值 | 描述 |
|---|---|---|
| `OBSIDIAN_API_KEY` | *(必填)* | 本地 REST API 外掛程式的 API 金鑰 |
| `OBSIDIAN_BASE_URL` | `http://127.0.0.1:27123` | REST API 端點 |
---
## 故障排除
### 註冊後工具未在 Claude Code 中顯示
Claude Code 只在會話啟動時讀取 MCP 設定。運行 `claude mcp add-json` 後，請開啟一個 **新的** Claude Code 會話。
### `~/Library/Logs/Claude/mcp-server-ultimate-obsidian.log` 不存在
日誌檔案僅在 Claude Code 成功啟動伺服器程序時建立。它的缺失意味著啟動失敗了 — 通常是路徑問題。
檢查：
1. `claude mcp get ultimate-obsidian` — 命令路徑是否正確？
2. 運行 `scripts/test-mcp.sh` 在隔離環境中測試啟動
3. 確保 `command` 欄位使用 **絕對路徑** 到 node，而不是僅 `node`
### `OBSIDIAN_API_KEY` 環境變數必填
MCP 註冊中缺少環境變數。刪除並重新新增：
```bash
claude mcp remove ultimate-obsidian -s user
claude mcp add-json -s user ultimate-obsidian '{ ... }'
```
### Obsidian 未運行 / REST API 返回連線拒絕
本地 REST API 外掛程式僅在 Obsidian 開啟時提供服務。在使用工具之前，請啟動 Obsidian。使用 `check_health` 驗證連線。
### `~/.claude/settings.json` 中的 `mcpServers` 無效
`~/.claude/settings.json` 不被 Claude Code CLI 用於 MCP 設定。該鍵由 Claude 桌面應用程式使用。CLI 從 `~/.claude.json` 讀取 — 請始終使用 `claude mcp add` 或 `claude mcp add-json` 註冊伺服器。
---
## 開發
```bash
# 僅類型檢查
npx tsc --noEmit
# 建構
npm run build
# 測試啟動（需要 Obsidian 運行）
OBSIDIAN_API_KEY=your-key node dist/index.js </dev/null 2>&1 &
sleep 1; kill %1 2>/dev/null
# 完整冒煙測試
bash scripts/test-mcp.sh
```
原始碼佈局：
```
src/
index.ts — MCP 伺服器入口點，啟動日誌，請求處理程式
tools.ts — 工具註冊表（TOOLS 陣列）和 handleTool 分發器
client.ts — ObsidianClient：REST API 的類型包裝器
sqlite.ts — SQLite FTS5 會話索引，用於 search_sessions / index_note
scripts/
test-mcp.sh — 模擬 Claude Code 的限制啟動環境的冒煙測試
migrate.ts — 從舊的 ~/.claude/memory/ 任務記憶體格式遷移
```
---
## 許可證
MIT
