PyGithub MCP 服务器
一个模型上下文协议服务器，提供通过 PyGithub 与 GitHub API 交互的工具。该服务器使 AI 助手能够执行 GitHub 操作，例如管理问题、存储库和拉取请求。
特征
- 模块化工具架构：
- 可配置的工具组，可启用/禁用
- 特定领域的组织（问题、存储库等）
- 通过文件或环境变量进行灵活配置
- 通过模块化设计明确分离关注点
- 通过一致的模式轻松扩展
- 完整的 GitHub 问题管理：
- 创建和更新问题
- 获取问题详细信息并列出存储库问题
- 添加、列出、更新和删除评论
- 管理问题标签
- 处理受让人和里程碑
- 智能参数处理：
- 为可选参数构建动态 kwargs
- GitHub 对象的正确类型转换
- 验证所有输入参数
- 清除无效输入的错误消息
- 稳健的实施：
- 通过 PyGithub 进行面向对象的 GitHub API 交互
- 集中式 GitHub 客户端管理
- 适当的错误处理和速率限制
- 通过 MCP 工具清理 API 抽象
- 全面的分页支持
- 用于调试的详细日志记录
文档
docs/guides 目录中提供了全面的指南：
- error-handling.md：错误类型、处理模式和最佳实践
- security.md：身份验证、访问控制和内容安全
- tool-reference.md：带有示例的详细工具文档
有关使用 PyGithub MCP 服务器的详细信息，请参阅这些指南。
使用示例
发行操作
- 创建问题
{
"owner": "username",
"repo": "repository",
"title": "Issue Title",
"body": "Issue description",
"assignees": ["username1", "username2"],
"labels": ["bug", "help wanted"],
"milestone": 1
}
- 获取问题详细信息
{
"owner": "username",
"repo": "repository",
"issue_number": 1
}
- 更新问题
{
"owner": "username",
"repo": "repository",
"issue_number": 1,
"title": "Updated Title",
"body": "Updated description",
"state": "closed",
"labels": ["bug", "wontfix"]
}
评论操作
- 添加评论
{
"owner": "username",
"repo": "repository",
"issue_number": 1,
"body": "This is a comment"
}
- 上市评论
{
"owner": "username",
"repo": "repository",
"issue_number": 1,
"per_page": 10
}
- 更新评论
{
"owner": "username",
"repo": "repository",
"issue_number": 1,
"comment_id": 123456789,
"body": "Updated comment text"
}
标签操作
- 添加标签
{
"owner": "username",
"repo": "repository",
"issue_number": 1,
"labels": ["enhancement", "help wanted"]
}
- 移除标签
{
"owner": "username",
"repo": "repository",
"issue_number": 1,
"label": "enhancement"
}
所有操作都智能地处理可选参数：
- 仅包含 API 调用中提供的参数
- 将原始类型转换为 GitHub 对象（例如，里程碑编号转换为里程碑对象）
- 为无效参数提供清晰的错误消息
- 在适用的情况下自动处理分页
安装
- 创建并激活虚拟环境：
uv venv
source .venv/bin/activate
- 安装依赖项：
配置
基本配置
将服务器添加到您的 MCP 设置（例如， claude_desktop_config.json或cline_mcp_settings.json ）：
{
"mcpServers": {
"github": {
"command": "/path/to/repo/.venv/bin/python",
"args": ["-m", "pygithub_mcp_server"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
}
}
}
}
工具组配置
服务器支持通过配置选择性地启用或禁用工具组。您可以通过两种方式进行配置：
1.配置文件
创建一个 JSON 配置文件（例如pygithub_mcp_config.json ）：
{
"tool_groups": {
"issues": {"enabled": true},
"repositories": {"enabled": true},
"pull_requests": {"enabled": false},
"discussions": {"enabled": false},
"search": {"enabled": true}
}
}
然后在您的环境中指定此文件：
export PYGITHUB_MCP_CONFIG=/path/to/pygithub_mcp_config.json
2.环境变量
或者，使用环境变量来配置工具组：
export PYGITHUB_ENABLE_ISSUES=true
export PYGITHUB_ENABLE_REPOSITORIES=true
export PYGITHUB_ENABLE_PULL_REQUESTS=false
默认情况下，仅启用issues工具组。更多详细配置选项请参阅README.config.md 。
发展
测试
该项目包括一个全面的测试套件：
# Run all tests
pytest
# Run tests with coverage report
pytest --cov
# Run specific test file
pytest tests/test_operations/test_issues.py
# Run tests matching a pattern
pytest -k "test_create_issue"
注意：许多测试目前失败，正在调查中。这是一个已知问题，正在积极处理中。
使用 MCP Inspector 进行测试
在开发过程中使用 MCP Inspector 测试 MCP 工具：
source .venv/bin/activate # Ensure venv is activated
npx @modelcontextprotocol/inspector -e GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here uv run pygithub-mcp-server
使用 MCP Inspector 的 Web UI 可以执行以下操作：
- 尝试可用的工具
- 使用真实的 GitHub 存储库进行测试
- 验证成功和错误情况
- 记录工作有效载荷
项目结构
tests/
├── unit/ # Fast tests without external dependencies
│ ├── config/ # Configuration tests
│ ├── tools/ # Tool registration tests
│ └── ... # Other unit tests
└── integration/ # Tests with real GitHub API
├── issues/ # Issue tools tests
└── ... # Other integration tests
src/
└── pygithub_mcp_server/
├── __init__.py
├── __main__.py
├── server.py # Server factory (create_server)
├── version.py
├── config/ # Configuration system
│ ├── __init__.py
│ └── settings.py # Configuration management
├── tools/ # Modular tool system
│ ├── __init__.py # Tool registration framework
│ └── issues/ # Issue tools
│ ├── __init__.py
│ └── tools.py # Issue tool implementations
├── client/ # GitHub client functionality
│ ├── __init__.py
│ ├── client.py # Core GitHub client
│ └── rate_limit.py # Rate limit handling
├── converters/ # Data transformation
│ ├── __init__.py
│ ├── parameters.py # Parameter formatting
│ ├── responses.py # Response formatting
│ ├── common/ # Common converters
│ ├── issues/ # Issue-related converters
│ ├── repositories/ # Repository converters
│ └── users/ # User-related converters
├── errors/ # Error handling
│ ├── __init__.py
│ └── exceptions.py # Custom exceptions
├── operations/ # GitHub operations
│ ├── __init__.py
│ └── issues.py
├── schemas/ # Data models
│ ├── __init__.py
│ ├── base.py
│ ├── issues.py
│ └── ...
└── utils/ # General utilities
├── __init__.py
└── environment.py # Environment utilities
故障排除
- 服务器启动失败：
- 在 MCP 设置中验证 venv Python 路径
- 确保所有要求都已安装在 venv 中
- 检查 GITHUB_PERSONAL_ACCESS_TOKEN 是否已设置且有效
- 构建错误：
- 在 uv build 中使用 --no-build-isolation 标志
- 确保使用的是 Python 3.10+
- 验证所有依赖项均已安装
- GitHub API 错误：
- 检查令牌权限和有效性
- 查看 pygithub_mcp_server.log 以获取详细的错误跟踪
- 验证是否未超出速率限制
依赖项
- Python 3.10+
- MCP Python SDK
- 派丹蒂克
- PyGithub
- UV包管理器
执照
麻省理工学院