AI导哈

GitHub知识库连接器

一个连接AI助手与GitHub上Obsidian知识库的协议服务器，实现笔记的读取、搜索和分析功能。

  • by Hint-Services
  • TypeScript
  • 本地部署
  • 10 星标
  • 更新于
在 GitHub 查看 Hint-Services/mcp-private-github-search

使用说明

黑曜石GitHub MCP

一个模型上下文协议（MCP）服务器，将AI助手连接到包含黑曜石保管库的GitHub存储库。此服务器可与存储在GitHub上的知识库无缝集成，允许AI助手阅读、搜索和分析您的黑曜石笔记和文档。

为什么是这个工具？

许多黑曜石用户将他们的保管库存储在GitHub中，用于备份、版本控制和协作。此MCP服务器弥合了GitHub托管的黑曜石保管库和AI助手之间的差距，实现了：

  • 知识库访问：从黑曜石金库中检索特定的笔记和文件
  • 智能搜索：在整个知识库中查找相关内容
  • 进化追踪：看看你的想法和笔记是如何随着时间的推移而发展的
  • 任务集成：与问题和项目管理工作流程联系起来

特性

  • GitHub存储库访问：连接到包含您的黑曜石保管库的任何GitHub存储库
  • 类型安全实施：用TypeScript编写，具有全面的类型定义
  • 输入验证：使用Zod模式对所有API输入进行稳健验证
  • 错误处理：优雅的错误处理，信息丰富
  • MCP集成：与Claude、Cursor、Windsurf、Cline和其他MCP主机完全兼容

可用工具

知识库访问

  • 获取文件内容：从黑曜石保管库中检索特定笔记、文档或文件的内容
  • 搜索文件：通过多种模式增强搜索：
    • filename：按确切的文件名查找文件（非常适合“OKR 2025”类型搜索）
    • path：在文件路径中的任何位置搜索
    • content：在文件内容中搜索
    • all：跨文件名、路径和内容的全面搜索

项目管理集成

  • 搜索问题：搜索与您的知识库项目相关的问题和讨论
  • getCommit历史：通过详细的提交历史和差异来跟踪您的知识库随时间的发展

用例

面向知识工作者

  • 研究助理：AI可以访问您的研究笔记和参考资料
  • 写作支持：从您的知识库中提取相关背景信息
  • 思想发展：跟踪笔记中的概念是如何演变的

对于开发者

  • 文档访问：检索项目文件和技术说明
  • 学习期刊：访问您的学习笔记和代码示例
  • 项目规划：与GitHub issues集成，实现全面的项目管理

面向学生和学者

  • 研究材料：获取课堂讲稿和学习指南
  • 研究论文：检索研究笔记和引文
  • 协作：使用存储在GitHub中的共享知识库

安装

使用Smithery（推荐）

安装Obsidian GitHub MCP的最简单方法是使用Smithery：

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

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

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

# For 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：包含黑曜石保险库的存储库名称

GitHub令牌权限

您的GitHub令牌需要以下权限：

  • repo （适用于私有存储库）或 public_repo （适用于公共存储库）
  • read:org （如果访问组织存储库）

示例工作流

访问您的每日笔记

{
  "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
  }
}

搜索提示和故障排除

无法按名称查找您的文件？

问题：搜索“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          # Main MCP server entry point
│   └── github/           # GitHub API integration
│       ├── client.ts     # GitHub client implementation
│       └── types.ts      # TypeScript type definitions
├── docs/                 # Documentation
├── package.json          # Project configuration
└── tsconfig.json         # TypeScript configuration

对于开发者

如果您有兴趣为此项目做出贡献或使用此服务器开发自己的工具，请参阅 开发指南.

开发命令

  • pnpm install -安装依赖项
  • pnpm run build -构建项目
  • pnpm run dev -使用检查器在开发模式下运行
  • pnpm run inspector -启动MCP检查员进行测试

从mcp私有github搜索迁移

如果你从旧的迁移 mcp-private-github-search 包裹：

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

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

  2. 功能保持不变-所有现有工具的工作方式相同

  3. 考虑新的以黑曜石为重点的用例和工作流程

了解更多

有关MCP生态系统的更多信息，请参阅：

关于提示服务

“未来已经到来，只是分布不均”

--威廉·吉布森，作家

Hint Services是一家精品咨询公司，其使命是开发和扩展用户界面如何利用人工智能技术。我们在人工智能和用户体验的交叉点构建雄心壮志，由Ben Hofferber创立和领导。

我们为希望在不成为开发人员的情况下采用人工智能工具的设计团队提供专门的人工智能研讨会。 了解更多关于我们的培训和研讨会.

相关 MCP