星战科技xingzhan.cloud
返回市场
黑曜石-github-mcp

黑曜石-github-mcp

作者：Hint-Services7 星标更新：2025-11-11
安装使用来源：spider==github.com

项目介绍

smithery 徽章 npm 版本

Obsidian GitHub MCP

这是一个模型上下文协议（MCP）服务器，它连接AI助手与包含Obsidian知识库的GitHub仓库。此服务器使您的GitHub存储的知识库能够无缝集成，允许AI助手读取、搜索和分析您的Obsidian笔记和文档。

为什么使用这个工具？

许多Obsidian用户将他们的知识库存储在GitHub上以进行备份、版本控制和协作。这个MCP服务器填补了您托管在GitHub上的Obsidian知识库与AI助手之间的空白，使得：

  • 知识库访问：从您的Obsidian知识库中检索特定的笔记和文档
  • 智能搜索：在整个知识库中查找相关内容
  • 进化追踪：查看您的想法和笔记如何随着时间发展
  • 任务整合：与问题和项目管理流程连接

功能

  • GitHub仓库访问：连接到任何包含您的Obsidian知识库的GitHub仓库
  • 类型安全实现：用TypeScript编写，并具有全面的类型定义
  • 输入验证：使用Zod模式对所有API输入进行强大的验证
  • 错误处理：优雅的错误处理并带有信息性消息
  • MCP集成：完全兼容Claude、Cursor、Windsurf、Cline和其他MCP主机

可用工具

知识库访问

  • getFileContents：检索您的Obsidian知识库中的特定笔记、文档或文件的内容
  • searchFiles：增强的搜索功能，支持多种模式：
    • filename：通过精确文件名查找文件（适用于“OKR 2025”类型的搜索）
    • path：在文件路径中任意位置搜索
    • content：在文件内容中搜索
    • all：跨文件名、路径和内容进行全面搜索

项目管理整合

  • searchIssues：搜索与您的知识库项目相关的议题和讨论
  • getCommitHistory：通过详细的提交历史记录和差异跟踪您的知识库如何随时间演变

使用案例

对于知识工作者

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

对于开发者

  • 文档访问：检索项目文档和技术笔记
  • 学习日志：访问您的学习笔记和代码示例
  • 项目规划：与GitHub议题集成，实现全面的项目管理

对于学生和学者

  • 学习材料：访问讲座笔记和学习指南
  • 研究论文：检索研究笔记和引用
  • 合作：与存储在GitHub上的共享知识库一起工作

安装

使用Smithery（推荐）

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

# 对于Claude桌面版
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（如果访问组织仓库）

示例工作流

访问您的日常笔记

{
  "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": "机器学习算法",
    "searchIn": "content",
    "perPage": 10
  }
}

综合搜索（文件名、路径和内容）

{
  "tool": "searchFiles",
  "arguments": {
    "query": "项目规划",
    "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": "\"项目规划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生态系统的信息，请参考：

关于Hint Services

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

—— 威廉·吉布森，作家

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

我们为设计团队提供专门的AI研讨会，这些团队希望拥抱AI工具而不必成为开发者。了解更多关于我们的培训和研讨会。