Obsidian MCP Server

🚀 Obsidian MCP 服務器

Obsidian MCP 服務器是基於 Model Context Protocol 的功能模塊，可在 Obsidian 的 vault 中實現強大的文件與內容管理能力。藉助調用工具資源，它能執行復雜的文本處理和內容操作。

🚀 快速開始

Obsidian MCP 服務器能助力開發者在 Obsidian vault 中實現複雜的文本處理和文件管理。下面為你介紹其安裝與配置步驟。

✨ 主要特性

文件管理

• 列表文件：可列出 vault 中指定目錄或根目錄下的所有文件。
• 讀取文件內容：返回指定路徑的文件內容。
• 創建/更新文件：支持原子操作，保障文件寫入過程安全可靠。

內容搜索

• 簡單文本搜索：在指定文件中查找關鍵詞，並返回上下文內容。
• 複雜搜索（JsonLogic）：依據自定義的 JsonLogic 表達式篩選文件和目錄。
• 標籤管理：獲取 vault 或特定目錄中的所有標籤信息。

屬性管理

• 查詢文件屬性：獲取指定文件的元數據，涵蓋標題、作者、類型等。
• 更新文件屬性：支持自定義字段更新，自動維護時間戳字段。

📦 安裝指南

安裝 MCP 服務器

npm install obsidian-mcp-server

配置 MCP 服務器

1. 在 package.json 中添加如下配置：

"mcp_server": {
  "vault_root": "./vault",  // 指定 vault 根目錄路徑
  "port": 3001,             // 可選，默認端口為 3001
  "log_level": "info"       // 可選，日誌級別：debug、info、warning、error
}

2. 啟動服務器

npm start

另一種安裝與配置方式

1. 克隆倉庫 首先，從 GitHub 倉庫下載代碼：

git clone https://github.com/mcptoolkit/obsidian-mcp-server.git

2. 安裝依賴 使用 npm 安裝項目所需的依賴包：

cd obsidian-mcp-server
npm install

3. 配置服務器參數 在 config.json 文件中填寫以下信息：

{
  "vault_root": "./vault",  // 指定 vault 根目錄
  "port": 3001,             // 可選，默認端口為 3001
  "log_level": "info"       // 可選，日誌級別：debug、info、warning、error
}

4. 啟動服務器 運行以下命令啟動 MCP 服務器：

npm start

💻 使用示例

基礎用法

文件管理

// 列出指定目錄下的文件
const result = await client.call("obsidian_list_files_in_dir", { dirpath: "./" });
console.log(result);

// 讀取文件內容
const content = await client.call("obsidian_get_file_contents", { filepath: "notes/README.md" });
console.log(content);

內容搜索

// 簡單文本搜索
const result = await client.call("obsidian_find_in_file", {
  filepath: "notes/index.md",
  query: "hello"
});
console.log(result);

// 複雜搜索（JsonLogic）
const result = await client.call("obsidian_complex_search", {
  query: "{ \"and\": [\n" +
         "  { \"glob\": [\"docs/*.md\", { \"var\": \"path\" } ] },\n" +
         "  { \"in\": [=\"#todo\", { \"var\": \"frontmatter.tags\" } ] }\n" +
         "] }"
});
console.log(result);

屬性管理

// 查詢文件屬性
const metadata = await client.call("obsidian_get_file_metadata", { filepath: "notes/todo.md" });
console.log(metadata);

// 更新文件屬性
const result = await client.call("obsidian_update_file_properties", {
  filepath: "notes/todo.md",
  properties: {
    priority: "high",
    due_date: "2024-03-15"
  }
});
console.log(result);

高級用法

自動化文件歸檔

通過設置定時任務，定期調用 MCP 服務器的 obsidian_list_files_in_dir 和 obsidian_move_file 接口，將指定目錄下的文件按日期歸檔。

const { DateTime } = require('luxon');

async function archiveOldFiles() {
  const today = DateTime.local().toISODate();
  const files = await client.call("obsidian_list_files_in_dir", { dirpath: "./old" });
  
  for (const file of files) {
    if (file.lastModified < today) {
      await client.call("obsidian_move_file", {
        from_path: `old/${file.name}`,
        to_path: `archived/${today}/${file.name}`
      });
    }
  }
}

setInterval(archiveOldFiles, 86400000); // 每天執行一次

內容自動分類

結合自然語言處理工具，定期分析文件內容並自動分類。

async function autoCategorize() {
  const files = await client.call("obsidian_list_files_in_dir", { dirpath: "./notes" });
  
  for (const file of files) {
    const content = await client.call("obsidian_get_file_contents", { filepath: `notes/${file.name}` });
    const category = getCategoryFromContent(content);
    
    if (category) {
      await client.call("obsidian_move_file", {
        from_path: `notes/${file.name}`,
        to_path: `${category}/${file.name}`
      });
    }
  }
}

setInterval(autoCategorize, 604800000); // 每週執行一次

📚 詳細文檔

工具接口

文件操作工具

// 列出 vault 中的所有文件
obsidian_list_files_in_vault: {
}

// 列出指定目錄下的文件
obsidian_list_files_in_dir: {
  dirpath: string; // 相對於 vault 根目錄的路徑
}

// 獲取文件內容
obsidian_get_file_contents: {
  filepath: string; // 相對於 vault 根目錄的路徑
}

搜索操作工具

// 在文件中查找文本並返回上下文
obsidian_find_in_file: {
  query: string,
  contextLength?: number  // 默認上下文長度為10
}

// 使用 JsonLogic 表達式進行復雜搜索
obsidian_complex_search: {
  query: JsonLogicQuery
  // 示例：
  // 按標籤查找："{"in": ["#mytag", {"var": "frontmatter.tags"}]}"
  //
  // 按目錄查找："{"glob": ["docs/*.md", {"var": "path"}]}"
  //
  // 組合條件："{"and": [
  //   {"glob": ["*.md", {"var": "path"}]},
  //   {"in": ["#mytag", {"var": "frontmatter.tags"}]}
  // ]}'
}

內容修改工具

// 追加內容到文件末尾
obsidian_append_content: {
  filepath: string,  // 相對於 vault 根目錄的路徑
  content: string    // 要追加的內容
}

// 替換文件內容
obsidian_patch_content: {
  filepath: string,  // 相對於 vault 根目錄的路徑
  content: string    // 新的內容
}

屬性管理工具

// 獲取文件元數據
obsidian_get_file_metadata: {
  filepath: string   // 相對於 vault 根目錄的路徑
}

// 更新文件屬性
obsidian_update_file_properties: {
  filepath: string,  // 相對於 vault 根目錄的路徑
  properties: {      // 需要更新的屬性
    [key: string]: any
  }
}

最佳實踐

1. 配置管理：確保正確配置 vault_root 和日誌級別，以便服務器正常運行。
2. 事務控制：對於涉及文件修改的操作，建議使用事務包裹，確保數據一致性。
3. 權限控制：根據實際需求設置訪問控制策略，防止未授權操作。

資源

• 官方文檔：Obsidian MCP Server 文檔
• 示例代碼：GitHub 示例倉庫

貢獻指南

1. 問題反饋：如有發現任何問題或漏洞，請在 Issues 中提交。
2. 功能建議：歡迎提出功能增強或優化的建議，我們會認真考慮每個合理的需求。
3. 開源貢獻：項目基於 MIT 協議開源，歡迎 fork 倉庫並提交 PR，共同完善這個工具。

常見問題

1. 如何處理大文件？：對於大文件，建議分塊處理或使用流式傳輸來提高效率。
2. 服務器性能不足怎麼辦？：可以通過優化代碼、增加內存或使用更高效的算法來提升性能。如果單機無法承擔負載，可以考慮分佈式部署。
3. 如何保證數據一致性？：在進行文件操作時，建議使用事務機制，確保每個操作要麼完全成功，要麼完全失敗，從而維護數據的一致性。

🔧 技術細節

Obsidian MCP 服務器基於 Model Context Protocol 構建，通過調用該協議的接口，實現了在 Obsidian vault 中的文件和內容管理功能。服務器使用 Node.js 開發，藉助 npm 進行依賴管理。在配置方面，可通過 package.json 或 config.json 文件指定 vault 根目錄、端口和日誌級別等參數。在文件操作上，支持原子操作，保證文件寫入的安全性；在內容搜索方面，提供了簡單文本搜索和基於 JsonLogic 的複雜搜索功能；在屬性管理方面，可查詢和更新文件的元數據。

📄 許可證

項目基於 MIT 協議開源。