AI导哈

GitHub仓库管理工具

一个提供GitHub仓库管理和文件访问功能的MCP服务器，适用于AI助手和本地开发工作流。

  • by aniketh1409
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 aniketh1409/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

可用工具

工具 说明 参数
list_repositories 列出用户的GitHub存储库 repo_type, sort, limit
get_repository_info 获取详细的存储库信息 repo_name
browse_repository 浏览存储库文件结构 repo_name, path, ref
read_file 从存储库读取文件内容 repo_name, file_path, ref
search_files 按名称/路径搜索文件 repo_name, query, file_type
search_code 在存储库中搜索代码内容 repo_name, query, language
clone_repository 将存储库克隆到本地文件系统 repo_name, local_path, branch
list_local_repositories 列出本地克隆的存储库 base_path

配置选项

存储库类型

  • 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！ 🎉

相关 MCP