Obsidian MCP Server

🚀 Obsidian MCP 服務器

Obsidian MCP 服務器是一個將 Obsidian 與模型上下文協議（MCP）相連接的服務器，它能實現模板化筆記管理、筆記間鏈接管理等功能，大大提升筆記的創建、檢索與關聯效率。

🚀 快速開始

安裝依賴

npm install

編譯 TypeScript

npm run build

配置環境變量

export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"
export OBSIDIAN_TEMPLATE_DIR="TEMPLATE"

⚠️ 重要提示

請將 OBSIDIAN_VAULT_PATH 替換為你實際的 Obsidian 保險庫路徑。

啟動服務器

npm start

✨ 主要特性

基本功能

• 使用模板創建筆記
• 讀取和更新筆記
• 獲取模板列表
• 管理和搜索標籤
• 搜索文件和目錄

鏈接管理功能（高優先級功能）

• 在筆記間創建維基鏈接
• 檢測和修復損壞的鏈接
• 分析反向鏈接並瞭解圖結構
• 自動生成內容地圖（目錄筆記）

📦 安裝指南

依賴安裝

npm install

代碼編譯

npm run build

環境變量設置

export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"
export OBSIDIAN_TEMPLATE_DIR="TEMPLATE"

服務器啟動

npm start

💻 使用示例

基礎用法

模板創建示例

TEMPLATE/meeting-notes.md 文件內容如下：

---
description: "用於創建會議筆記的模板"
---

# {{title}}

**日期時間**: {{date}} {{time}}
**參會人員**: {{participants}}

## 議程
{{agenda}}

## 會議記錄
{{notes}}

## 下次會議前的行動項
{{action_items}}

MCP 調用示例

// 從模板創建筆記
await mcp.callTool('create_note_from_template', {
  templateName: 'meeting-notes',
  variables: {
    title: '項目規劃會議',
    participants: '田中、佐藤、山田',
    agenda: '討論新功能的規格',
    notes: '',
    action_items: ''
  },
  outputPath: 'meetings/2024-01-15-project-planning.md'
});

// 創建筆記間鏈接
await mcp.callTool('link_notes', {
  sourceNote: 'meetings/2024-01-15-project-planning.md',
  targetNote: 'projects/new-feature.md',
  linkText: '新功能項目',
  insertPosition: 'end'
});

高級用法

鏈接管理工具使用示例

// 檢測損壞的鏈接
const brokenLinks = await mcp.callTool('find_broken_links');

// 反向鏈接分析
const backlinks = await mcp.callTool('analyze_backlinks', {
  targetNote: 'concepts/important-concept.md'
});

// 創建內容地圖
await mcp.callTool('create_moc', {
  title: '項目相關筆記',
  targetPath: 'index/project-moc.md',
  sourcePattern: 'project',
  groupBy: 'tag',
  includeDescription: true
});

📚 詳細文檔

MCP 配置方法

Claude Desktop 配置

1. 確認配置文件位置：
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/claude/claude_desktop_config.json
2. 確認項目路徑：

pwd

3. 確認 Node.js 路徑：

which node

4. 編輯配置文件： 在配置文件中添加以下配置：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/dist/server.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault",
        "OBSIDIAN_TEMPLATE_DIR": "TEMPLATE"
      }
    }
  }
}

配置示例：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/Users/username/Projects/obsidian-mcp-server/dist/server.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/Users/username/Documents/MyVault",
        "OBSIDIAN_TEMPLATE_DIR": "TEMPLATE"
      }
    }
  }
}

故障排除（明確指定 Node.js 路徑）：

{
  "mcpServers": {
    "obsidian": {
      "command": "/usr/local/bin/node",
      "args": ["/path/to/obsidian-mcp-server/dist/server.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault",
        "OBSIDIAN_TEMPLATE_DIR": "TEMPLATE"
      }
    }
  }
}

⚠️ 重要提示

• /path/to/obsidian-mcp-server/dist/server.js 請替換為實際的項目路徑
• /path/to/your/obsidian/vault 請替換為實際的 Obsidian 保險庫路徑
• /usr/local/bin/node 請替換為 which node 命令確認的 Node.js 路徑

5. 重啟 Claude Desktop

其他 MCP 客戶端配置

如果使用其他 MCP 客戶端，請參考以下配置：

• 命令：node /path/to/obsidian-mcp-server/dist/server.js
• 環境變量：
  • OBSIDIAN_VAULT_PATH：Obsidian 保險庫路徑
  • OBSIDIAN_TEMPLATE_DIR：模板目錄名稱

可用工具

1. create_note_from_template

使用模板創建 Obsidian 筆記。

2. list_templates

獲取 TEMPLATE 文件夾內可用的模板列表。

3. read_note

讀取 Obsidian 筆記的內容。

4. update_note

更新 Obsidian 筆記的內容。

5. list_tags

列出 Obsidian 保險庫內的所有標籤。

6. rename_tag

批量重命名 Obsidian 保險庫內的標籤。

7. search_files

在 Obsidian 保險庫內搜索文件和目錄。

鏈接管理工具（高優先級功能）

8. link_notes

在筆記間創建維基鏈接。

功能：

• 檢查文件是否存在
• 檢測並警告重複鏈接
• 解析相對路徑
• 以維基鏈接格式 [[目標|顯示文本]] 插入

9. find_broken_links

檢測並修復損壞的鏈接。

功能：

• 支持維基鏈接 [[]] 和 Markdown 鏈接 []()
• 通過模糊搜索提供修復候選
• 考慮大小寫、空格和特殊字符的差異
• 顯示行號和周邊上下文

返回值：

{
  "brokenLinks": [
    {
      "sourceFile": "notes/example.md",
      "linkText": "缺失的筆記",
      "targetPath": "missing-note",
      "lineNumber": 15,
      "suggestions": ["similar-note", "missing-note-backup"]
    }
  ],
  "totalCount": 1
}

10. analyze_backlinks

分析反向鏈接並瞭解圖結構。

功能：

• 檢測指向指定筆記的反向鏈接
• 提取鏈接周邊的上下文
• 識別相關筆記
• 計算流行度和中心性指標

返回值：

{
  "targetNote": "important-concept.md",
  "backlinks": [
    {
      "sourceFile": "notes/research.md",
      "context": "這個概念被稱為[[important-concept]]",
      "linkType": "wiki"
    }
  ],
  "relatedNotes": ["notes/research.md"],
  "metrics": {
    "popularity": 5,
    "centrality": 0.1
  }
}

11. create_moc

自動生成內容地圖（目錄筆記）。

功能：

• 通過模式匹配選擇文件
• 按標籤或文件夾分組
• 自動從 YAML frontmatter 中提取描述
• 以維基鏈接格式生成目錄

生成示例：

# 項目相關筆記

*此內容地圖是自動生成的 - 2024-01-15*

## #project
- [[project-planning|項目規劃]] - 新功能的規劃和設計
- [[project-timeline|項目時間表]] - 開發時間表和里程碑

## #development  
- [[api-design|API 設計]] - RESTful API 的規格說明
- [[database-schema|數據庫設計]] - 表結構和關係

📄 許可證

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