Obsidian Github MCP

🚀 Obsidian GitHub MCP

Obsidian GitHub MCP 是一個模型上下文協議（MCP）服務器，它能將 AI 助手與包含 Obsidian 保險庫的 GitHub 倉庫連接起來。該服務器可實現與存儲在 GitHub 上的知識庫無縫集成，使 AI 助手能夠讀取、搜索和分析你的 Obsidian 筆記與文檔。

🚀 快速開始

安裝

使用 Smithery（推薦）

使用 Smithery 安裝 Obsidian GitHub MCP 是最簡單的方式：

# 對於 Claude Desktop
npx -y @smithery/cli install @Hint-Services/obsidian-github-mcp --client claude

# 對於 Cursor
npx -y @smithery/cli install @Hint-Services/obsidian-github-mcp --client cursor

# 對於 Windsurf
npx -y @smithery/cli install @Hint-Services/obsidian-github-mcp --client windsurf

# 對於 Cline
npx -y @smithery/cli install @Hint-Services/obsidian-github-mcp --client cline

手動安裝

npm install obsidian-github-mcp

配置

將服務器添加到你的 MCP 設置文件中，並進行如下配置：

{
  "mcpServers": {
    "obsidianGithub": {
      "command": "npx",
      "args": ["-y", "obsidian-github-mcp"],
      "env": {
        "GITHUB_TOKEN": "your-github-token",
        "GITHUB_OWNER": "your-github-username",
        "GITHUB_REPO": "your-obsidian-vault-repo"
      }
    }
  }
}

必需的環境變量

• GITHUB_TOKEN：你的 GitHub 個人訪問令牌（在此創建）
• GITHUB_OWNER：GitHub 倉庫的所有者或組織
• GITHUB_REPO：包含你的 Obsidian 保險庫的倉庫名稱

GitHub 令牌權限

你的 GitHub 令牌需要以下權限：

• repo（適用於私有倉庫）或 public_repo（適用於公共倉庫）
• read:org（如果訪問組織倉庫）

✨ 主要特性

• GitHub 倉庫訪問：可連接到任何包含你的 Obsidian 保險庫的 GitHub 倉庫。
• 類型安全實現：使用 TypeScript 編寫，並具有全面的類型定義。
• 輸入驗證：使用 Zod 模式對所有 API 輸入進行強大的驗證。
• 錯誤處理：優雅地處理錯誤，並提供信息豐富的消息。
• MCP 集成：與 Claude、Cursor、Windsurf、Cline 等其他 MCP 主機完全兼容。

📦 可用工具

知識庫訪問

• getFileContents：從你的 Obsidian 保險庫中檢索特定筆記、文檔或文件的內容。
• searchFiles：具有多種模式的增強搜索功能：
  • filename：按精確文件名查找文件（非常適合“OKR 2025”類型的搜索）
  • path：在文件路徑的任何位置進行搜索
  • content：在文件內容中進行搜索
  • all：對文件名、路徑和內容進行全面搜索

項目管理集成

• searchIssues：搜索與你的知識庫項目相關的問題和討論。
• getCommitHistory：通過詳細的提交歷史記錄和差異跟蹤你的知識庫隨時間的演變。

💻 使用示例

基礎用法

訪問每日筆記

{
  "tool": "getFileContents",
  "arguments": {
    "filePath": "Daily Notes/2024-01-15.md"
  }
}

按名稱查找文件（非常適合“OKR 2025”示例！）

{
  "tool": "searchFiles",
  "arguments": {
    "query": "OKR 2025",
    "searchIn": "filename"
  }
}

高級用法

按路徑查找文件

{
  "tool": "searchFiles",
  "arguments": {
    "query": "Daily Notes",
    "searchIn": "path"
  }
}

查找關於某個主題的研究（內容搜索）

{
  "tool": "searchFiles",
  "arguments": {
    "query": "machine learning algorithms",
    "searchIn": "content",
    "perPage": 10
  }
}

全面搜索（文件名、路徑和內容）

{
  "tool": "searchFiles",
  "arguments": {
    "query": "project planning",
    "searchIn": "all"
  }
}

高級 GitHub 搜索語法

{
  "tool": "searchFiles",
  "arguments": {
    "query": "path:*.md extension:md",
    "searchIn": "content"
  }
}

跟蹤知識演變

{
  "tool": "getCommitHistory",
  "arguments": {
    "days": 30,
    "includeDiffs": true,
    "maxCommits": 10
  }
}

📚 使用案例

知識工作者

• 研究助手：AI 可以訪問你的研究筆記和參考資料。
• 寫作支持：從你的知識庫中提取相關的背景信息。
• 創意發展：跟蹤你的概念在筆記中的演變。

開發者

• 文檔訪問：檢索項目文檔和技術筆記。
• 學習日誌：訪問你的學習筆記和代碼示例。
• 項目規劃：與 GitHub 問題和項目管理工作流程集成。

學生和學者

• 學習材料：訪問講座筆記和學習指南。
• 研究論文：檢索研究筆記和引用。
• 協作：與存儲在 GitHub 上的共享知識庫進行協作。

📚 搜索提示與故障排除

按名稱找不到文件？

問題：搜索“OKR 2025”找不到名為“OKR 2025.md”的文件。 解決方案：使用 searchIn: "filename" 參數：

{
  "tool": "searchFiles",
  "arguments": {
    "query": "OKR 2025",
    "searchIn": "filename"
  }
}

高級搜索技巧

1. 精確短語：對於多詞搜索使用引號

   {
     "query": "\"project planning 2025\"",
     "searchIn": "content"
   }
   

2. 文件擴展名：查找特定文件類型

   {
     "query": "path:*.md",
     "searchIn": "content"
   }
   

3. 特定目錄：在文件夾內進行搜索

   {
     "query": "path:\"Daily Notes/\"",
     "searchIn": "content"
   }
   

🔧 項目結構

obsidian-github-mcp/
├── src/
│   ├── index.ts          # 主 MCP 服務器入口點
│   └── github/           # GitHub API 集成
│       ├── client.ts     # GitHub 客戶端實現
│       └── types.ts      # TypeScript 類型定義
├── docs/                 # 文檔
├── package.json          # 項目配置
└── tsconfig.json         # TypeScript 配置

📚 開發者相關

開發命令

• pnpm install - 安裝依賴項
• pnpm run build - 構建項目
• pnpm run dev - 在開發模式下運行並開啟檢查器
• pnpm run inspector - 啟動 MCP 檢查器進行測試

從 mcp-private-github-search 遷移

如果你從舊的 mcp-private-github-search 包遷移：

1. 在配置中更新你的包名：

   {
     "mcpServers": {
       "obsidianGithub": {
         "command": "npx",
         "args": ["-y", "obsidian-github-mcp"]
       }
     }
   }
   

2. 功能保持不變 - 所有現有工具的工作方式相同。
3. 考慮新的以 Obsidian 為中心的用例和工作流程。

📚 瞭解更多

有關 MCP 生態系統的更多信息，請參考：

• 模型上下文協議文檔：詳細介紹 MCP 架構和設計原則。
• Smithery - MCP 服務器註冊表：發佈 MCP 服務器的指南。
• MCP TypeScript SDK 文檔：全面的 TypeScript SDK 文檔。
• Obsidian：啟發此工具的知識管理應用程序。

📚 關於 Hint Services

“未來已然來臨，只是分佈不均”

— 威廉·吉布森，作家

Hint Services 是一家精品諮詢公司，致力於開發和拓展用戶界面如何利用人工智能技術。我們在人工智能和用戶體驗的交匯處規劃宏偉藍圖，由本·霍弗伯（Ben Hofferber）創立並領導。

我們為希望在不成為開發者的情況下采用 AI 工具的設計團隊提供專業的 AI 研討會。瞭解更多關於我們的培訓和研討會。