# github-mcp-server

**Repository Path**: yanxi-mcp/github-mcp-server

## Basic Information

- **Project Name**: github-mcp-server
- **Description**: github mcp server
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-01
- **Last Updated**: 2026-10-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GitHub MCP Server

基于 Python 与 MCP SDK 的 GitHub stdio 服务。GitHub REST API 调用位于 `app/github/`，MCP 工具注册位于 `app/tools/`。默认只注册只读工具；创建 Issue 和合并 PR 需要显式启用写入，并在每次调用中通过 MCP elicitation 请求确认。

## 安装与启动

需要 Python 3.12 或 3.13。在本目录执行 PowerShell：

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
$env:GITHUB_MCP_TOKEN = "<从安全存储读取的 PAT>"
.\.venv\Scripts\python.exe -m app.main
```

不要把真实 PAT 写入仓库、配置示例、终端历史或 MCP 对话。可由密码管理器或 MCP 客户端的安全环境变量配置提供 PAT。服务会把协议写到 stdout，审计和诊断写到 stderr。

MCP 客户端配置示例，路径和 PAT 来源需要按本机环境替换：

```json
{
  "mcpServers": {
    "github": {
      "command": "D:\\python_workplace\\github-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "app.main"],
      "env": {
        "GITHUB_MCP_TOKEN": "<由客户端安全注入的 PAT>"
      }
    }
  }
}
```

如需写操作，额外设置 `GITHUB_MCP_ENABLE_WRITES=true`。启用后，`create_issue` 和 `merge_pull_request` 才会出现在工具列表。服务会对每次写调用发起 MCP elicitation；客户端不支持确认、用户拒绝或取消时，不发送写入请求。创建 Issue 的确认提示展示完整标题和正文；标题最多 256 字符，正文最多 10000 字符。确认由客户端呈现，服务无法替客户端证明是谁点击了确认；请使用可信客户端。

合并前先调用 `get_pull_request` 取得 `head_sha` 和 `base_branch`，分别作为 `merge_pull_request` 的 `expected_head_sha` 和 `expected_base`。服务在确认提示中展示 PR 标题与目标分支，并在请求合并前再次读取 PR，检查两项预期值。GitHub 合并接口会原子校验 head SHA，但不提供目标分支的原子条件；极短的“复查目标分支后、发送合并前”并发改目标分支窗口仍然存在，请结合仓库分支保护规则使用。

## 工具

| 类别 | 工具 | 说明 |
|---|---|---|
| 仓库 | `get_repository` | 仓库概要，60 秒内存缓存 |
| Issue | `list_issues`、`get_issue` | 单页列表与详情；列表排除 PR |
| PR | `list_pull_requests`、`get_pull_request` | 单页列表与详情，详情包含 head SHA 与目标分支 |
| 提交 | `list_commits`、`get_commit` | 单页列表与提交摘要 |
| 搜索 | `search_repositories`、`search_issues` | GitHub 查询语法；Issue 搜索也可能返回 PR |
| 写入 | `create_issue`、`merge_pull_request` | 默认不注册，需要启用与逐次确认 |

列表与搜索每次最多 100 条，默认 30 条。GitHub 的 Issue 接口先分页再混合返回 Issue 和 PR；本服务过滤 PR 后，某页可能少于请求数量甚至为空，继续翻页仍可能有 Issue。仓库详情缓存 60 秒、最多 128 条。服务固定连接 `https://api.github.com`，不跟随重定向，不把 PAT 发送到自定义 API URL。主限流或次级限流会返回等待提示且不自动重试；请按提示稍后重试。日志包含 HTTP 方法、API 路径、状态码和耗时，不包含 PAT、查询词或请求体。若需长期留存审计，请由 MCP 宿主收集 stderr。

## PAT 权限

推荐使用限定仓库范围的 fine-grained PAT，并仅授予实际使用的权限。只读功能通常需要目标仓库的 `Metadata: read`、`Contents: read`、`Issues: read` 和 `Pull requests: read`，私有仓库的搜索结果也受 PAT 可见范围约束。创建 Issue 需要 `Issues: write`；合并 PR 需要 `Contents: write`。GitHub 对每个端点列出的权限为准：

- [认证与 PAT](https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api)
- [创建 Issue](https://docs.github.com/en/rest/issues/issues#create-an-issue)
- [合并 PR](https://docs.github.com/en/rest/pulls/pulls#merge-a-pull-request)
- [API 限流](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api)

## 验证

```powershell
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m ruff format --check .
```

测试只使用本地模拟 HTTP 传输与 MCP 内存客户端，不需要真实 PAT 或网络连接。