MCP 服务器

PyGithub MCP Server

使 AI 助手能够通过 PyGithub 库与 GitHub 交互，提供用于管理问题、存储库、拉取请求和其他 GitHub 操作的工具，并具有智能参数处理和错误管理功能。

版本控制

Tools

create_issue

Create a new issue in a GitHub repository. Args: params_dict: Parameters for creating an issue including: - owner: Repository owner (user or organization) - repo: Repository name - title: Issue title - body: Issue description (optional) - assignees: List of usernames to assign - labels: List of labels to add - milestone: Milestone number (optional) Returns: Created issue details from GitHub API

list_issues

List issues from a GitHub repository. Args: params: Parameters for listing issues including: - owner: Repository owner (user or organization) - repo: Repository name - state: Issue state (open, closed, all) - labels: Filter by labels - sort: Sort field (created, updated, comments) - direction: Sort direction (asc, desc) - since: Filter by date - page: Page number for pagination - per_page: Number of results per page (max 100) Returns: List of issues from GitHub API

get_issue

Get details about a specific issue. Args: params: Parameters for getting an issue including: - owner: Repository owner (user or organization) - repo: Repository name - issue_number: Issue number to retrieve Returns: Issue details from GitHub API

update_issue

Update an existing issue. Args: params: Parameters for updating an issue including: - owner: Repository owner (user or organization) - repo: Repository name - issue_number: Issue number to update - title: New title (optional) - body: New description (optional) - state: New state (optional) - labels: New labels (optional) - assignees: New assignees (optional) - milestone: New milestone number (optional) Returns: Updated issue details from GitHub API

add_issue_comment

Add a comment to an issue. Args: params: Parameters for adding a comment including: - owner: Repository owner (user or organization) - repo: Repository name - issue_number: Issue number to comment on - body: Comment text Returns: Created comment details from GitHub API

list_issue_comments

List comments on an issue. Args: params: Parameters for listing comments including: - owner: Repository owner (user or organization) - repo: Repository name - issue_number: Issue number - since: Filter by date (optional) - page: Page number (optional) - per_page: Results per page (optional) Returns: List of comments from GitHub API

update_issue_comment

Update an issue comment. Args: params: Parameters for updating a comment including: - owner: Repository owner (user or organization) - repo: Repository name - issue_number: Issue number containing the comment - comment_id: Comment ID to update - body: New comment text Returns: Updated comment details from GitHub API

push_files

Push multiple files to a GitHub repository in a single commit. Args: params: Dictionary with file parameters - owner: Repository owner (username or organization) - repo: Repository name - branch: Branch to push to - files: List of files to push, each with path and content - message: Commit message Returns: MCP response with file push result

delete_issue_comment

Delete an issue comment. Args: params: Parameters for deleting a comment including: - owner: Repository owner (user or organization) - repo: Repository name - issue_number: Issue number containing the comment - comment_id: Comment ID to delete Returns: Empty response on success

add_issue_labels

Add labels to an issue. Args: params: Parameters for adding labels including: - owner: Repository owner (user or organization) - repo: Repository name - issue_number: Issue number - labels: Labels to add Returns: Updated list of labels from GitHub API

remove_issue_label

Remove a label from an issue. Args: params: Parameters for removing a label including: - owner: Repository owner (user or organization) - repo: Repository name - issue_number: Issue number - label: Label to remove Returns: Empty response on success or error if label doesn't exist

get_repository

Get details about a GitHub repository. Args: params: Dictionary with repository parameters - owner: Repository owner (username or organization) - repo: Repository name Returns: MCP response with repository details

create_repository

Create a new GitHub repository. Args: params: Dictionary with repository creation parameters - name: Repository name - description: Repository description (optional) - private: Whether the repository should be private (optional) - auto_init: Initialize repository with README (optional) Returns: MCP response with created repository details

fork_repository

Fork an existing GitHub repository. Args: params: Dictionary with fork parameters - owner: Repository owner (username or organization) - repo: Repository name - organization: Organization to fork to (optional) Returns: MCP response with forked repository details

search_repositories

Search for GitHub repositories. Args: params: Dictionary with search parameters - query: Search query - page: Page number for pagination (optional) - per_page: Results per page (optional) Returns: MCP response with matching repositories

get_file_contents

Get contents of a file in a GitHub repository. Args: params: Dictionary with file parameters - owner: Repository owner (username or organization) - repo: Repository name - path: Path to file/directory - branch: Branch to get contents from (optional) Returns: MCP response with file content data

create_or_update_file

Create or update a file in a GitHub repository. Args: params: Dictionary with file parameters - owner: Repository owner (username or organization) - repo: Repository name - path: Path where to create/update the file - content: Content of the file - message: Commit message - branch: Branch to create/update the file in - sha: SHA of file being replaced (for updates, optional) Returns: MCP response with file creation/update result

create_branch

Create a new branch in a GitHub repository. Args: params: Dictionary with branch parameters - owner: Repository owner (username or organization) - repo: Repository name - branch: Name for new branch - from_branch: Source branch (optional, defaults to repo default) Returns: MCP response with branch creation result

list_commits

List commits in a GitHub repository. Args: params: Dictionary with commit parameters - owner: Repository owner (username or organization) - repo: Repository name - page: Page number (optional) - per_page: Results per page (optional) - sha: Branch name or commit SHA (optional) Returns: MCP response with list of commits

README

PyGithub MCP 服务器

一个模型上下文协议服务器，提供通过 PyGithub 与 GitHub API 交互的工具。此服务器使 AI 助手能够执行 GitHub 操作，例如管理 issue、仓库和 pull request。

功能

模块化工具架构：
- 可配置的工具组，可以启用/禁用
- 领域特定的组织（issue、仓库等）
- 通过文件或环境变量进行灵活配置
- 通过模块化设计实现清晰的关注点分离
- 易于扩展，具有一致的模式
完整的 GitHub Issue 管理：
- 创建和更新 issue
- 获取 issue 详细信息并列出仓库 issue
- 添加、列出、更新和删除评论
- 管理 issue 标签
- 处理 assignee 和 milestone
智能参数处理：
- 为可选参数构建动态 kwargs
- 为 GitHub 对象进行正确的类型转换
- 验证所有输入参数
- 为无效输入提供清晰的错误消息
强大的实现：
- 通过 PyGithub 进行面向对象的 GitHub API 交互
- 集中式 GitHub 客户端管理
- 正确的错误处理和速率限制
- 通过 MCP 工具进行清晰的 API 抽象
- 全面的分页支持
- 详细的调试日志记录

文档

全面的指南可在 docs/guides 目录中找到：

error-handling.md：错误类型、处理模式和最佳实践
security.md：身份验证、访问控制和内容安全
tool-reference.md：详细的工具文档和示例

请参阅这些指南，了解有关使用 PyGithub MCP 服务器的详细信息。

使用示例

Issue 操作

创建 Issue

{
  "owner": "username",
  "repo": "repository",
  "title": "Issue Title",
  "body": "Issue description",
  "assignees": ["username1", "username2"],
  "labels": ["bug", "help wanted"],
  "milestone": 1
}

获取 Issue 详细信息

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1
}

更新 Issue

{
  "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 对象（例如，将 milestone 编号转换为 Milestone 对象）
为无效参数提供清晰的错误消息
在适用的情况下自动处理分页

安装

创建并激活虚拟环境：

uv venv
source .venv/bin/activate

安装依赖项：

uv pip install -e .

配置

基本配置

将服务器添加到您的 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。

开发

测试

该项目包含一个全面的测试套件：

# 运行所有测试
pytest

# 运行带有覆盖率报告的测试
pytest --cov

# 运行特定的测试文件
pytest tests/test_operations/test_issues.py

# 运行匹配模式的测试
pytest -k "test_create_issue"

注意：许多测试当前失败并且正在调查中。这是一个已知问题，正在积极处理中。

使用 MCP Inspector 进行测试

在开发期间使用 MCP Inspector 测试 MCP 工具：

source .venv/bin/activate  # 确保 venv 已激活
npx @modelcontextprotocol/inspector -e GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here uv run pygithub-mcp-server

使用 MCP Inspector 的 Web UI 来：

试验可用的工具
使用真实的 GitHub 仓库进行测试
验证成功和错误情况
记录有效负载

项目结构

tests/
├── unit/                # 没有外部依赖的快速测试
│   ├── config/          # 配置测试
│   ├── tools/           # 工具注册测试
│   └── ...              # 其他单元测试
└── integration/         # 使用真实 GitHub API 的测试
    ├── issues/          # Issue 工具测试
    └── ...              # 其他集成测试

src/
└── pygithub_mcp_server/
    ├── __init__.py
    ├── __main__.py
    ├── server.py        # 服务器工厂 (create_server)
    ├── version.py
    ├── config/          # 配置系统
    │   ├── __init__.py
    │   └── settings.py  # 配置管理
    ├── tools/           # 模块化工具系统
    │   ├── __init__.py  # 工具注册框架
    │   └── issues/      # Issue 工具
    │       ├── __init__.py
    │       └── tools.py # Issue 工具实现
    ├── client/          # GitHub 客户端功能
    │   ├── __init__.py
    │   ├── client.py    # 核心 GitHub 客户端
    │   └── rate_limit.py # 速率限制处理
    ├── converters/      # 数据转换
    │   ├── __init__.py
    │   ├── parameters.py # 参数格式化
    │   ├── responses.py # 响应格式化
    │   ├── common/      # 通用转换器
    │   ├── issues/      # Issue 相关转换器
    │   ├── repositories/ # 仓库转换器
    │   └── users/       # 用户相关转换器
    ├── errors/          # 错误处理
    │   ├── __init__.py
    │   └── exceptions.py # 自定义异常
    ├── operations/      # GitHub 操作
    │   ├── __init__.py
    │   └── issues.py
    ├── schemas/         # 数据模型
    │   ├── __init__.py
    │   ├── base.py
    │   ├── issues.py
    │   └── ...
    └── utils/           # 通用实用程序
        ├── __init__.py
        └── environment.py # 环境实用程序

故障排除

服务器启动失败：
- 验证 MCP 设置中的 venv Python 路径
- 确保所有要求都已安装在 venv 中
- 检查 GITHUB_PERSONAL_ACCESS_TOKEN 是否已设置且有效
构建错误：
- 将 --no-build-isolation 标志与 uv build 一起使用
- 确保正在使用 Python 3.10+
- 验证是否已安装所有依赖项
GitHub API 错误：
- 检查令牌权限和有效性
- 查看 pygithub_mcp_server.log 以获取详细的错误跟踪
- 验证是否已超过速率限制

依赖项

Python 3.10+
MCP Python SDK
Pydantic
PyGithub
UV 包管理器

许可证

MIT