🚀 MCP GitHub 仓库服务器
MCP GitHub 仓库服务器基于模型上下文协议（MCP），可让AI助手便捷地浏览与读取指定GitHub仓库内的文件，实现对仓库内容的高效访问。
🚀 快速开始
配置环境变量
服务器运行依赖以下环境变量，请按需配置：
GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token
GITHUB_OWNER=repository_owner
GITHUB_REPO=repository_name
GITHUB_BRANCH=branch_name # 可选
安装依赖
npm install
构建服务器
npm run build
开发模式
若需自动重建开发，可执行：
npm run watch
与Claude Desktop集成
在Claude Desktop中使用时，需添加服务器配置：
配置位置
- MacOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"mcp-server-github-repo": {
"command": "/path/to/mcp-server-github-repo/build/index.js"
}
}
}
✨ 主要特性
资源访问
- 灵活文件访问：可通过URI访问仓库中的任意文件。
- 内容导航：支持列出仓库内容并导航目录。
- 分支特定访问：支持分支特定的文件访问。
- 纯文本输出：文件内容以纯文本格式提供。
资源URI规范
- 基本URL格式：
https://api.github.com/repos/{owner}/{repo}/contents/{path} - 类型支持：支持文件和目录，文件使用
text/plainMIME类型，目录使用application/x-directoryMIME类型。
📦 安装指南
与Claude Desktop一起使用时，按上述配置位置添加服务器配置即可完成安装。
💻 使用示例
基础用法
通过基本URL格式访问仓库资源，例如访问特定文件：
https://api.github.com/repos/owner/repo/contents/path/to/file.txt
高级用法
若要访问特定分支的文件，可在URL中指定分支：
https://api.github.com/repos/owner/repo/contents/path/to/file.txt?ref=branch_name
📚 详细文档
API 实现
服务器实现了三个主要MCP端点：
ListResources- 列出仓库中的文件和目录ReadResource- 获取特定文件的内容
认证机制
服务器使用GitHub个人访问令牌进行认证，请确保您的令牌具有适当的权限以访问仓库内容。
错误处理
服务器包含以下错误处理机制：
- 环境变量缺失
- GitHub API错误
- 无效路径（例如尝试将目录读取为文件）
- 认证失败
调试方法
由于MCP服务器通过stdio通信，调试可能具有挑战性。可使用MCP Inspector进行调试：
npm run inspector
这将提供一个访问浏览器中的调试工具的URL。
🔧 技术细节
服务器借助GitHub API实现对仓库资源的访问，通过环境变量配置仓库信息和认证令牌。在处理请求时，根据不同的MCP端点和资源URI，调用相应的GitHub API接口获取资源，并对返回结果进行处理和格式化。同时，服务器包含完善的错误处理机制，以应对各种可能的异常情况。
📄 许可证
本项目采用MIT许可证。
演示
⚠️ 重要提示
请保持GitHub个人访问令牌的安全，考虑使用权限最小的令牌，并注意仓库大小限制，以免影响访问大型仓库。
💡 使用建议
在开发过程中，可使用
npm run watch命令进行带自动重建的开发，提高开发效率。调试时，使用MCP Inspector可更方便地进行问题排查。