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 研讨会。了解更多关于我们的培训和研讨会。