GitHub MCP Assistant

GitHub MCP 连接器

一个模型上下文协议（MCP）服务器，为AI助手提供GitHub存储库管理和文件访问功能。

特征：

核心存储库管理

• 列出存储库：通过过滤和排序浏览所有GitHub存储库
• 存储库信息：获取有关任何存储库的详细信息
• 文件浏览：远程导航存储库文件结构
• 文件读取：从任何存储库读取文件内容
• 代码搜索：跨存储库搜索代码内容
• 文件搜索：按名称或路径查找文件

本地开发工作流程

• 克隆存储库：将GitHub存储库克隆到本地文件系统
• 本地存储库管理：列出并管理本地克隆的存储库
• 智能组织：自动组织克隆的存储库 ~/github/{owner}/{repo} 结构

安装

0.先决条件

• Python 3.10+ 是必需的（MCP框架要求）

1.克隆和设置

# Clone the repository
git clone https://github.com/yourusername/github-mcp-connector.git
cd github-mcp-connector

# Run the setup script
python setup.py

2.安装依赖项

选项A：使用紫外线（推荐-更快！）

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

选项B：使用pip

pip install -r requirements.txt

2.获取GitHub Token

1. 转到GitHub→ 设置→ 开发人员设置→ 个人访问令牌
2. 生成具有以下作用域的新令牌：

- repo （完全控制私有存储库） - public_repo （访问公共存储库） - user （读取用户配置文件数据）

3.设置环境变量

选项A：使用.env文件（推荐）

# Copy the example environment file
cp env.example .env

# Edit .env with your actual GitHub token
# GITHUB_TOKEN=your_actual_token_here

选项B：直接设置环境变量

# On Windows PowerShell
$env:GITHUB_TOKEN="your_token_here"

# On Windows CMD
set GITHUB_TOKEN=your_token_here

# On macOS/Linux
export GITHUB_TOKEN=your_token_here

4.在MCP客户端注册

复制并自定义示例配置：

# For Claude Desktop
cp claude_desktop_config.example.json ~/.config/claude/claude_desktop_config.json

# For other MCP clients  
cp mcp_server_config.example.json your_mcp_config.json

或者手动添加到MCP客户端配置中：

{
  "mcpServers": {
    "github-connector": {
      "command": "python",
      "args": ["/absolute/path/to/your/github_server.py"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

重要提示：

• 替换 /absolute/path/to/your/github_server.py 与实际路径
• 确保您的 GITHUB_TOKEN 环境变量已设置
• 永远不要提交包含您实际令牌的文件

使用示例

库管理

列出您的存储库：

Can you show me my GitHub repositories?

获取存储库详细信息：

Get information about my repository "my-awesome-project"

浏览存储库结构：

Show me the file structure of microsoft/vscode

文件操作

读取文件：

Read the README.md file from facebook/react

搜索文件：

Find all Python files containing "main" in the django/django repository

搜索代码内容：

Search for "async function" in microsoft/typescript

地方发展

克隆存储库：

Clone the repository microsoft/vscode to my local machine

列出本地存储库：

Show me all the GitHub repositories I have cloned locally

可用工具

配置选项

存储库类型

• all：所有存储库（默认）
• public：仅限公共存储库
• private：仅限私有存储库
• owner：您拥有的存储库

排序选项

• updated：最近更新（默认）
• created：最近创建
• pushed：最近推
• full_name：按字母顺序排列

错误处理🔧

服务器处理常见场景：

• 速率限制：尊重GitHub API费率限制
• 认证：清除令牌问题的错误消息
• 文件访问：适当处理二进制文件和大文件
• 网络问题：妥善处理连接问题

发展

项目结构

├── github_server.py                    # Main MCP server implementation
├── requirements.txt                    # Python dependencies (pip)
├── pyproject.toml                      # Project configuration (uv/modern Python)
├── setup.py                           # Setup script for easy configuration
├── test_setup.py                      # Setup verification script
├── env.example                        # Example environment variables
├── mcp_server_config.example.json     # Example MCP configuration
├── claude_desktop_config.example.json # Example Claude Desktop configuration
├── .gitignore                         # Git ignore patterns (protects secrets)
└── README.md                          # This file

依赖项

• mcp>=1.0.0：模型上下文协议框架
• PyGithub>=2.1.1：GitHub API客户端
• GitPython>=3.1.40：本地存储库的Git操作
• aiohttp>=3.9.0：异步HTTP客户端
• pydantic>=2.0.0：数据验证

运行服务器

紫外线（推荐）：

# Run directly
uv run python github_server.py

# Or activate virtual environment first
uv venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows
python github_server.py

使用pip：

python github_server.py

uv开发

# Install with dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Format code
uv run black .
uv run ruff check .

GitHub代币安全

• 最小范围：仅授予 repo, public_repo，以及 user 范围
• 代币轮换：定期重新生成您的个人访问令牌
• 安全存储：将令牌存储在环境变量中，而不是代码文件中
• 访问控制：令牌继承您的GitHub权限

服务器安全

• 仅限本地：服务器在本地运行，从不向外部服务公开令牌
• 速率限制：自动遵守GitHub的API速率限制
• 错误处理：在不暴露敏感数据的情况下提供详细的错误消息
• 权限：仅访问您有权查看的存储库

开发最佳实践

• 始终使用 setup.py 初始配置脚本
• 测试用 test_setup.py 在生产中使用之前
• 保持依赖关系更新 uv sync 或 pip install -U
• 使用示例配置作为模板，永远不要共享真实的配置

局限性

• 搜索速率限制：GitHub代码搜索有更严格的速率限制
• 大文件：超过1MB的文件可能会被截断
• 二进制文件：不显示二进制文件（但可以检测到）
• 私人存储库：需要适当的令牌权限

未来的增强功能

未来版本的计划功能：

• 问题管理（创建、更新、评论）
• 拉取请求操作（创建、审核、合并）
• 分支管理（创建、切换、删除）
• 提交操作（提交、推送更改）
• Webhook管理
• GitHub操作集成

贡献

请随时提交问题和增强请求！

许可证

您可以在自己的项目中自由使用它。 由Aniketh Kini制作

准备好将您的AI助手连接到GitHub！ 🎉