github-mcp-server

GitHub MCP 服务

最全面的 GitHub MCP 服务——提供完整的 GitHub 工作流自动化，包括 Actions 监控、高级 PR 管理、智能代码搜索和完整的文件管理。专为 AI 驱动的开发团队打造。

👉 初次使用？请参阅快速入门指南

🚀 为 AI 优化，提升 Token 效率

此服务专为 AI Agent 打造：

响应格式

格式	使用场景	Token 节省
compact	发现、列表、状态检查	缩小 80-97%
json	需要时查看完整详情	完整响应
markdown	便于阅读的显示	格式化文本

实际节省效果

资源	完整 JSON	Compact	节省
提交	~3,000 字符	~100 字符	97%
Issue	~2,500 字符	~150 字符	94%
仓库	~4,000 字符	~200 字符	95%
PR 概览	~20,000 字符	~1,800 字符	91%（GraphQL）

智能用法

// Default: Use compact for most operations
const issues = await callMCPTool("github_list_issues", {
  owner: "user", repo: "repo",
  limit: 10,
  response_format: "compact"  // 94% smaller!
});

// Use json only when you need every field
const fullIssue = await callMCPTool("github_get_issue", {
  owner: "user", repo: "repo",
  issue_number: 42,
  response_format: "json"
});

结合我们以代码为先的架构（减少 98% 的 Token），即可获得目前最高效的 GitHub MCP 服务。

📖 文档：

• Token 效率指南 - 按工具详细说明节省效果（效率提升 18 倍）
• 响应格式参考 - 完整的 compact 字段列表

✨ 最新动态

🚀 最新版本：v2.5.6 - AI 优化与 Token 效率（2025 年 12 月 18 日）

• 📦 Compact 格式推广 - 现在有 26 个工具支持 response_format: "compact"（节省 80-97% 的 Token！）
• 🔧 ETag 缓存修复 - 修复了 304 响应时缓存返回空数据的严重错误
• 📖 AI 通用指南 - 将 CLAUDE.md 重命名为 MCP_GUIDE.md，并添加适用于 Claude、Cursor、Windsurf、Copilot、Cline 的说明
• 🔒 安全工具文档 - 为 Dependabot、Code Scanning、Secret Scanning 工具添加权限要求
• 📊 GraphQL 优化 - 通过 GraphQL 获取的 PR 概览比对应的 REST 版本小 91%
• ✅ 320 项测试通过 - 完整的 CI 验证

v2.5.5 - 已准备好接入 MCP Registry（2025 年 12 月 17 日）

• 🔄 移除了仅限管理员使用的工具（delete_repository、transfer_repository）
• ➕ 添加了删除工具（delete_release、delete_gist）
• 🔧 修复了 create_branch、create_file、create_pull_request 的返回数据
• ✅ 测试覆盖范围扩展至 320 项测试

此前版本：v2.5.1 - 架构重构与性能优化（2025 年 12 月 9 日）

• 🏗️ 模块化架构 - github_mcp.py 拆分为模块化的包结构
• ⚡ 连接池 - 延迟降低 97%（后续调用从 4000ms 降至 108ms）
• 🔧 Dict→Model 转换 - callMCPTool 现在可与普通 JavaScript 对象无缝协作
• 📝 多行代码支持 - 修复截断问题，全面支持 JSON 协议
• ✅ 实时集成测试 - 15/15 项通过，共 320 项测试
• 📦 21 个工具模块 - 结构清晰：tools/、models/、utils/、auth/

此前版本：v2.5.0 - 第二阶段全面发布（2025 年 12 月 4 日）

**重大版本：**新增 47 个工具（总数从 62 个增至 109 个）！全面覆盖 GitHub API。

v2.5.0 新增内容：

• 🚀 GitHub Actions 扩展（12 个工具）- 完整的工作流管理：获取／触发工作流、管理运行／作业、管理构件
• 🔒 安全套件（13 个工具）- Dependabot、Code Scanning、Secret Scanning、安全公告
• 📋 Projects（9 个工具）- 经典项目看板：列出／创建／更新项目、管理列
• 💬 Discussions（7 个工具）- 社区讨论：列出／获取讨论、管理类别和评论、创建／更新讨论、添加评论（GraphQL）
• 🔔 通知（6 个工具）- 用户通知：列出／管理会话、管理订阅
• 👥 协作者与团队（3 个工具）- 仓库访问管理

此前版本：v2.4.0 - 第一阶段工具扩展（2025 年 12 月 4 日）

新增 15 个工具（总数从 48 个增至 62 个）！

v2.4.0 新增内容：

• 🎯 Issue 评论 - 使用 github_add_issue_comment 为 Issue 添加评论
• 📝 Gist - 完整的 CRUD 操作：github_list_gists、github_get_gist、github_create_gist、github_update_gist
• 🏷️ 标签 - 完整的标签管理：github_list_labels、github_create_label、github_delete_label
• ⭐ Star 用户 - 为仓库加星／取消加星：github_list_stargazers、github_star_repository、github_unstar_repository
• 👤 用户上下文 - 增强的用户操作：github_get_authenticated_user、github_list_user_repos、github_list_org_repos、github_search_users
• ✅ 恢复 - github_get_user_info 已重新加入 TypeScript 定义

此前版本：v2.3.1 - 默认强制启用代码优先模式（2025 年 1 月 26 日）

• 🎯 默认强制启用 - 代码优先模式现在默认为 true（之前为 false）
• 🚀 零配置 - 新用户自动获得 98% 的 token 用量降低
• ✅ 文档一致性 - 代码现在与文档中的说明一致
• 🔧 架构完整性 - 真正的代码优先 MCP 参考实现

此前版本：v2.3.0 - 架构正式确立（2025 年 1 月 26 日）

**单工具架构正式确立：**从第一天起便是预期设计——一个工具，减少 98% 的 token 用量！

v2.3.0 新增内容：

• 🎯 明确架构 - 正式确立单工具设计（始终是预期架构）
• 🛠️ CLI 实用工具 - 将开发诊断功能移至 CLI（github-mcp-cli）
• 📊 测试质量提升 - 320 项测试，覆盖率 63%（此前为 181 项测试，覆盖率 55%）
• ✅ 新增 33 项测试 - 全面覆盖身份验证、实用工具和工具操作
• 📝 文档更新 - 提供清晰的架构文档和 CLI 用法

---

v2.2.0 - 企业级就绪（2025 年 11 月 20 日）

GitHub App 身份验证： 速率限制提升至 3 倍（每小时 15,000 次请求，而非 5,000 次），并支持细粒度权限！

v2.2.0 新增内容：

• 🔐 GitHub App 身份验证 - 企业级身份验证，基于安装授权访问
• ⚡ 3 倍速率限制 - 每小时 15,000 次请求，而 PAT 为 5,000 次
• 🔄 双重身份验证 - 自动从 App 回退到 PAT
• 🐛 19 项身份验证修复 - 确保所有工具的身份验证一致
• ✅ 100% 向后兼容 - 不影响现有 PAT 用户

---

v2.1.0 - 增强工具发现（2025 年 11 月 19 日）

工具调用失败归零： 智能工具发现消除发现问题，同时保持 98% 的令牌效率！

v2.1.0 新增内容：

🔍 工具发现函数

• listAvailableTools() - 按需发现所有工具
• searchTools(query) - 按关键词查找相关工具
• getToolInfo(name) - 获取完整架构和示例
• 在代码中发现 - 不会向 Claude 的上下文加载额外令牌！

优势：

• ✅ 因发现问题导致的工具调用失败归零
• ✅ 专业的首次用户体验
• ✅ 保持 98% 的令牌用量缩减
• ✅ 所有工具的完整类型信息

---

🎉 v2.0.0 - 革命性的代码优先架构（2025 年 11 月 18 日）

变革性突破： 令牌用量缩减 98%（70,000 → 800 个令牌）！

新架构：

• 仅向 Claude 提供单个 execute_code 工具
• 编写 TypeScript 代码，按需调用 112 个工具
• 初始化速度提升 95%（45s → 2s）
• 工作流成本降低 98%（每个工作流 $1.05 → $0.01）

工具总数： 向 MCP 客户端提供 1 个工具（execute_code）🚀
内部工具： 61 个 GitHub 工具可通过 execute_code 使用
令牌效率： 与传统 MCP 相比，令牌用量缩减 98%

---

📦 近期发布

v1.5.0（2025 年 11 月 6 日） - 基础设施升级

• 以仓库为根目录的操作和分块读取
• GraphQL 优化（PR 查询速度提升 80%）

查看完整更新日志

---

工作区配置

工作区工具（workspace_grep、workspace_str_replace、workspace_read_file）可对你的项目执行强大的本地文件操作。

什么是工作区工具？

这些工具可让 Claude：

• 🔍 高效搜索你的代码库（workspace_grep）
• ✏️ 精确编辑文件（workspace_str_replace）
• 📖 分块读取文件，无需加载整个文件（workspace_read_file）

设置工作区根目录

方法 1：Claude Desktop 配置

编辑 Claude Desktop 配置文件（位置因操作系统而异）：

macOS：

{
  "mcpServers": {
    "github-mcp": {
      "command": "python3",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "MCP_WORKSPACE_ROOT": "/Users/yourname/projects/my-app"
      }
    }
  }
}

Windows：

{
  "mcpServers": {
    "github-mcp": {
      "command": "python",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "MCP_WORKSPACE_ROOT": "C:\\Users\\yourname\\projects\\my-app"
      }
    }
  }
}

Linux：

{
  "mcpServers": {
    "github-mcp": {
      "command": "python3",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "MCP_WORKSPACE_ROOT": "/home/yourname/projects/my-app"
      }
    }
  }
}

方法 2：环境变量

macOS/Linux：

export MCP_WORKSPACE_ROOT="/path/to/your/project"
python3 -m github_mcp

Windows（命令提示符）：

set MCP_WORKSPACE_ROOT=C:\path\to\your\project
python -m github_mcp

Windows（PowerShell）：

$env:MCP_WORKSPACE_ROOT="C:\path\to\your\project"
python -m github_mcp

方法 3：默认行为

如果未设置 MCP_WORKSPACE_ROOT，工具将使用当前工作目录作为工作区根目录。

工作区安全性

• ✅ 工具只能访问工作区根目录内的文件
• ✅ 会阻止路径遍历尝试
• ✅ 无法访问项目目录以外的内容
• ✅ 可安全用于生产环境

使用示例

# After setting MCP_WORKSPACE_ROOT="/Users/dave/my-app"

# Search for TODOs in your project
workspace_grep("TODO", file_pattern="*.py")

# Read a specific file chunk
workspace_read_file("src/main.py", start_line=1, num_lines=50)

# Make surgical edits
workspace_str_replace(
    path="config/settings.py",
    old_str="DEBUG = True",
    new_str="DEBUG = False",
    description="Disable debug mode for production"
)

使用场景

• 🔧 本地开发： 提交前处理文件
• 🔍 代码搜索： 查找整个项目中的模式
• ✏️ 重构： 精确修改文件，无需操作 GitHub
• 📊 分析： 读取并分析代码结构

GitHub 远程工具

无需克隆，即可直接在 GitHub 上处理文件：

• github_grep - 搜索 GitHub 仓库文件中的模式

  • 推送更改后，验证代码是否存在
  • 跨分支或在特定提交中搜索
  • 无需克隆，即可在远程仓库中查找模式
  • 与获取完整文件相比，可节省 90% 以上的 token

• github_read_file_chunk - 读取 GitHub 文件中的指定行范围

  • 只读取所需行（50-500 行）
  • 非常适合审查函数或代码段
  • 与获取完整文件相比，可节省 90% 以上的 token

• github_str_replace - 对 GitHub 文件进行精准编辑

  • 无需克隆，即可直接在 GitHub 上更新文件
  • 非常适合快速修复、版本更新或文档更改
  • 需要对仓库拥有写入权限

完整工作流：

1. 使用工作区工具在本地开发（速度快、节省 token）
2. 通过 git 推送更改
3. 使用 GitHub 工具在 GitHub 上验证（确认更改已生效）
4. 如有需要，直接在 GitHub 上快速修复

---

🏗️ 架构：代码优先 MCP

工作原理

GitHub MCP Server 采用代码优先架构——这是一种革命性方法，在保持完整功能的同时，可将 token 用量减少 98%。

你看到的内容

在 MCP 客户端（Cursor、Claude Desktop 等）中安装此服务后：

• 一个工具： execute_code
• Token 成本： 约 800 个 token
• 全部功能： 可使用 109 个 GitHub 工具

实际运行机制

┌─────────────────────────────────┐
│   MCP Client                    │
│   Sees: execute_code (1 tool)   │
└────────────┬────────────────────┘
             │
             ↓ You write TypeScript code
┌─────────────────────────────────┐
│   Deno Runtime                  │
│   Executes your code securely   │
│   Access to all internal tools  │
│   via callMCPTool()             │
└─────────────────────────────────┘

传统 MCP 与代码优先 MCP

方面	传统 MCP	代码优先 MCP（本项目）
暴露的工具	112 个工具	1 个工具
Token 成本	约 70,000 个	约 800 个
减少比例	-	98%
功能	相同	相同
灵活性	仅工具调用	代码 + 逻辑 + 循环

这为何重要

• 大幅节省 token： 减少 98% 意味着响应更快、成本更低
• 复杂工作流： 在单次执行中组合多项操作
• 条件逻辑： 使用 if/else、循环及完整的编程能力
• 功能不变： 仍可使用全部 112 个工具（111 个内部工具 + execute_code 封装器）

这种架构验证了 Anthropic 对代码优先 MCP 的研究预测。

🔍 工具发现

GitHub MCP Server 包含强大的工具发现功能，可帮助你快速查找和了解工具。

searchTools(keyword)

按关键词搜索工具。搜索工具名称、描述、类别和参数，并根据相关性评分。

示例：

// Find all issue-related tools
const issueTools = searchTools("issue");
// Returns: Array of tools sorted by relevance

issueTools.forEach(tool => {
  console.log(`${tool.name} (relevance: ${tool.relevance})`);
  console.log(`  Category: ${tool.category}`);
  console.log(`  Matched in: ${tool.matchedIn.join(", ")}`);
});

// Output:
// github_create_issue (relevance: 15)
//   Category: Issues
//   Matched in: name, description

返回：

Array<{
  name: string;           // Tool name
  category: string;       // Category (e.g., "Issues")
  description: string;    // Tool description
  relevance: number;      // Relevance score (higher = better match)
  matchedIn: string[];    // Where matches were found
  tool: object;          // Full tool object
}>

相关性评分：

• 匹配工具名称：+10 分
• 匹配描述：+5 分
• 匹配类别：+3 分
• 匹配参数名称：+2 分
• 匹配参数描述：+1 分

getToolInfo(toolName)

获取特定工具的完整详情，包括参数、用法和元数据。

示例：

// Get detailed info about a tool
const info = getToolInfo("github_create_issue");

console.log(`Name: ${info.name}`);
console.log(`Category: ${info.category}`);
console.log(`Description: ${info.description}`);
console.log(`Usage: ${info.usage}`);

// See metadata
console.log(`Total tools: ${info.metadata.totalTools}`);
console.log(`Tools in category: ${info.metadata.categoryTools}`);

// Check parameters
Object.entries(info.parameters).forEach(([name, param]) => {
  console.log(`${name}: ${param.type} ${param.required ? '(required)' : '(optional)'}`);
  console.log(`  ${param.description}`);
});

返回：

{
  name: string;              // Tool name
  category: string;          // Category
  description: string;       // Description
  parameters: object;        // Parameter definitions
  returns: string;           // Return value description
  example: string;           // Code example
  usage: string;            // Usage syntax
  metadata: {
    totalTools: number;      // Total available tools
    categoryTools: number;   // Tools in same category
    relatedCategory: string; // Category name
  }
}

错误处理：

const info = getToolInfo("nonexistent_tool");
// Returns: { error: "Tool not found", suggestion: "Use searchTools()...", availableTools: 42 }

工作流示例：发现 → 了解 → 使用

// 1. Discover tools
const prTools = searchTools("pull request");
console.log(`Found ${prTools.length} PR-related tools`);

// 2. Learn about the best match
const bestMatch = prTools[0];
const info = getToolInfo(bestMatch.name);
console.log(`Using: ${info.name}`);
console.log(`Required params: ${Object.keys(info.parameters).filter(k => info.parameters[k].required).join(", ")}`);

// 3. Use the tool
const result = await callMCPTool(info.name, {
  owner: "facebook",
  repo: "react",
  state: "open"
});

可用的发现功能

函数	用途	返回内容
listAvailableTools()	获取按类别整理的所有工具	完整工具目录
searchTools(keyword)	按关键词查找工具	按相关性排序的匹配项
getToolInfo(toolName)	获取工具完整详情	工具完整信息
callMCPTool(name, params)	执行工具	工具结果

这些发现操作在你的 TypeScript 代码内部完成——不会向 Claude 的上下文中加载额外工具！

开发实用工具（CLI）

为便于服务诊断和开发，我们提供 CLI 命令（这些不是 MCP 工具）：

# Check server health
github-mcp-cli health

# Clear GitHub App token cache  
github-mcp-cli clear-cache

# Verify Deno runtime installation
github-mcp-cli check-deno

注意： 这些 CLI 实用工具仅用于开发和调试。它们不会暴露给 MCP 客户端，是在开发期间为测试服务本身而创建的。

简易设置

macOS/Linux：

{
  "mcpServers": {
    "github": {
      "command": "python3",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Windows：

{
  "mcpServers": {
    "github": {
      "command": "python",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

注意： 架构强制采用代码优先模式，无需额外配置。自动节省 98% 的令牌。

就是这样！默认即可节省 98% 的令牌。🚀

了解更多

• 📖 代码执行指南 - 完整文档
• 💡 示例 - 实际使用示例
• 🚀 快速入门 - 5 分钟完成设置

---

🙏 基于 Anthropic 的研究构建

此服务实现了 Anthropic 研究中介绍的代码优先 MCP 模式：

📄 博客： "使用 MCP 执行代码"
👥 作者： Adam Jones 和 Conor Kelly

他们的预测： 令牌减少 98.7%（150,000 → 2,000 个令牌）
我们的验证： 令牌减少 98%（70,000 → 800 个令牌）

感谢 Anthropic 团队率先开创了这一方法！🎉

详细了解我们的实现 →

要求

• 已安装 Deno 运行时
• GitHub 身份验证（Personal Access Token 或 GitHub App）

---

⚙️ 配置与身份验证

双重身份验证策略（推荐）

为获得最佳功能和速率限制，你可以配置两种身份验证方式，但大多数用户只需使用 PAT 即可开始：

{
  "mcpServers": {
    "github-mcp": {
      "command": "python",
      "args": ["-m", "github_mcp"],
      "env": {
        // === Personal Access Token (Simple default - REQUIRED for releases) ===
        "GITHUB_TOKEN": "ghp_your_personal_access_token_here",
        
        // === Optional: GitHub App Authentication (Advanced) ===
        "GITHUB_APP_ID": "123456",
        "GITHUB_APP_INSTALLATION_ID": "12345678",
        "GITHUB_APP_PRIVATE_KEY_PATH": "/path/to/private-key.pem",
        
        // === Optional: Workspace for local file operations ===
        "MCP_WORKSPACE_ROOT": "/path/to/your/project"
      }
    }
  }
}

为什么要使用两种身份验证方式？

🏆 GitHub App 身份验证（高级）

• 速率限制： 每小时 15,000 次请求（比 PAT 高 3 倍）
• 适用场景： 大多数操作、团队协作、生产环境
• 涵盖： 仓库管理、问题、PR、文件、搜索、工作流

设置 GitHub App：

1. 前往 GitHub Settings → Developer settings → GitHub Apps → New GitHub App
2. 设置权限：Contents（读/写）、Issues（读/写）、Pull requests（读/写）、Metadata（读取）
3. 在你的账户/组织中安装该应用
4. 生成并下载私钥
5. 记下你的 App ID 和 Installation ID

🔑 Personal Access Token（必需的备用方式）

• 速率限制： 每小时 5,000 次请求
• 必需用途： 发布操作（GitHub App 的限制）
• 也涵盖： GitHub App 不可用时的所有操作

为什么需要 PAT：

GitHub App 存在权限限制——无法创建/管理涉及提交打标签的发布（GitHub App 不提供“releases”权限范围）。以下操作需要使用 PAT 作为备用方式：

• ✅ github_create_release - 创建带标签的发布
• ✅ github_update_release - 更新发布信息
• ✅ 任何涉及给非 HEAD 提交打标签的操作

即使已配置 GitHub App，服务也会在这些操作中自动回退到 PAT。

创建 PAT：

1. 前往 GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. 生成新令牌，并选择权限范围：repo、workflow
3. 复制令牌（之后将无法再次查看！）

身份验证行为

Operation Requested
    ↓
Try GitHub App (if configured)
    ↓
├─ Success → Use App (15k rate limit) ✅
└─ Fails or requires releases permission
       ↓
   Fall back to PAT (if configured)
       ↓
   ├─ Success → Use PAT (5k rate limit) ✅
   └─ Fails → Return auth error ❌

快速入门配置

大多数用户只需要 Personal Access Token：

1. 创建 GitHub PAT：

• 前往 https://github.com/settings/tokens
• 点击 "Generate new token (classic)"
• 选择权限范围：repo、workflow、read:org
• 复制令牌

2. 配置你的 MCP 客户端：

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "github": {
      "command": "python",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

或使用系统环境变量：

在 shell 配置文件或系统环境设置中设置 GITHUB_TOKEN。

就是这样！现在你可以使用全部 112 个工具了。

💡 需要更高的速率限制？ 高级用户可以创建自己的 GitHub App，将每小时请求数从 5,000 提高到 15,000。

平台专属示例

macOS

{
  "mcpServers": {
    "github-mcp": {
      "command": "python3",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_APP_ID": "123456",
        "GITHUB_APP_INSTALLATION_ID": "12345678",
        "GITHUB_APP_PRIVATE_KEY_PATH": "/Users/yourname/.github/private-key.pem",
        "GITHUB_TOKEN": "ghp_your_token",
        "MCP_WORKSPACE_ROOT": "/Users/yourname/projects/my-app"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "github-mcp": {
      "command": "python",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_APP_ID": "123456",
        "GITHUB_APP_INSTALLATION_ID": "12345678",
        "GITHUB_APP_PRIVATE_KEY_PATH": "C:\\Users\\yourname\\.github\\private-key.pem",
        "GITHUB_TOKEN": "ghp_your_token",
        "MCP_WORKSPACE_ROOT": "C:\\Users\\yourname\\projects\\my-app"
      }
    }
  }
}

Linux

{
  "mcpServers": {
    "github-mcp": {
      "command": "python3",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_APP_ID": "123456",
        "GITHUB_APP_INSTALLATION_ID": "12345678",
        "GITHUB_APP_PRIVATE_KEY_PATH": "/home/yourname/.github/private-key.pem",
        "GITHUB_TOKEN": "ghp_your_token",
        "MCP_WORKSPACE_ROOT": "/home/yourname/projects/my-app"
      }
    }
  }
}

环境变量参考

变量	必需	描述
GITHUB_TOKEN	是*	个人访问令牌（发布时必需）
GITHUB_APP_ID	否	GitHub App ID（速率限制提高 3 倍）
GITHUB_APP_INSTALLATION_ID	否	GitHub App 的安装 ID
GITHUB_APP_PRIVATE_KEY_PATH	否	GitHub App 私钥的路径（.pem 文件）
GITHUB_APP_PRIVATE_KEY	否	私钥内容（用于 CI/CD）
GITHUB_AUTH_MODE	否	强制使用的身份验证方式："app" 或 "pat"（默认自动选择）
MCP_WORKSPACE_ROOT	否	本地文件操作的根目录

*需要设置 GITHUB_TOKEN 或全部三个 GitHub App 变量

身份验证故障排除

“需要身份验证”错误

1. ✅ 确认已设置有效的 GITHUB_TOKEN
2. ✅ 检查令牌是否具有 repo 和 workflow 作用域
3. ✅ 如果使用 GitHub App，请确认安装 ID 正确
4. ✅ 确认私钥路径正确且文件存在

当前使用哪种身份验证方式？

• 查看服务日志：[OK] Using GitHub App authentication 或 [OK] Using PAT authentication
• 如果已配置，优先尝试 GitHub App
• 发布操作会自动回退到 PAT
• 手动覆盖：设置 GITHUB_AUTH_MODE=pat 以强制使用 PAT

速率限制对比

身份验证方式	每小时请求数	最适用场景
GitHub App	15,000	大多数操作、生产环境
PAT	5,000	快速设置、发布操作
两者（双重）	15,000 + 回退	推荐——兼具两者优势

发布操作因“403”或“需要身份验证”而失败

• ✅ 如果只配置了 GitHub App，这是预期行为
• ✅ **解决方案：**添加 GITHUB_TOKEN，以便在回退时使用 PAT
• ✅ GitHub App 无法创建发布（API 限制）
• ✅ 服务会在这些操作中自动回退到 PAT

启用调试日志：

GITHUB_MCP_DEBUG_AUTH=true

这会输出身份验证诊断信息，帮助排查问题。

所有配置选项请参阅 env.example。

诊断工具

如需调试和诊断，请使用 CLI 工具（这些工具不会作为 MCP 工具公开）：

# Check server health
github-mcp-cli health

# Clear GitHub App token cache (after permission updates)
github-mcp-cli clear-cache

# Verify Deno installation
github-mcp-cli check-deno

注意：这些工具供开发者和运维人员使用。MCP 服务仅公开一个工具（execute_code），以维持其减少 98% 令牌用量的价值主张。

---

🏆 质量保证与测试

元级自验证

此 MCP 服务实现了一项独特能力：通过自身执行来测试自身。

我们的测试套件在 Cursor IDE 中运行，使用 GitHub MCP Server 测试 GitHub MCP Server。工具通过递归执行来验证自身。

测试结果：

• ✅ 320/320 项测试通过（通过率 100%）
• ✅ 代码覆盖率 63%（全面的测试套件）
• ✅ 自动发现未发现任何问题
• ✅ 自验证架构
• ✅ 元级：∞（实现无限递归）

这对你意味着：

• 工具已通过自执行证明可正常工作
• TypeScript 与 Python 之间的契约已验证
• 全面的测试覆盖（320 项测试，覆盖率 63%）
• 自动问题检测
• 最高级别的质量保证

质量指标

• 测试覆盖率：63%（320 项全面测试）
• 测试通过率：100%
• 类型覆盖率：100%（Mypy 严格模式）
• 代码质量：0 个 lint 错误（Ruff）
• 安全性：0 个漏洞（pip-audit）
• CI/CD：4 项质量门禁（lint、类型、安全、测试）
• 元级成就：工具测试自身（∞）

详细了解我们的测试理念 →

**📖 需要详细的设置说明？**请参阅 GitHub App 高级指南

---

🔒 安全性

代码执行沙箱

GitHub MCP Server 为代码执行实现了多层安全防护：

1. 代码验证：执行前验证所有 TypeScript 代码，以阻止以下行为：

   • 调用 eval() 和 new Function()
   • 使用危险的 Deno API（写入文件、启动进程等）
   • 尝试原型污染
   • 动态构造代码的模式
   • 嵌套层级过深（防止 DoS）

2. Deno 沙箱：代码在权限受限的 Deno 环境中运行：

   • 网络访问仅限 GitHub API
   • 无文件系统写入权限
   • 无法启动子进程
   • 执行超时时间为 60 秒

3. 错误信息净化：净化错误信息，防止信息泄露。

报告安全问题

如果您发现安全漏洞，请发送邮件至 [email protected]，不要公开提交问题。

---

📋 错误处理

所有代码执行响应均采用标准格式，以便统一处理错误。

成功响应：

{
  "error": false,
  "data": { /* your result */ }
}

错误响应：

{
  "error": true,
  "message": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": { /* optional context */ }
}

标准错误代码包括：VALIDATION_ERROR、EXECUTION_ERROR、TIMEOUT、TOOL_ERROR、TOOL_NOT_FOUND、INVALID_PARAMS 等。

📖 完整错误处理指南 →

---

🚀 功能概览

📦 仓库管理（7 个工具）

涵盖从创建到归档的完整仓库生命周期管理。

• 仓库信息 - 全面的元数据、统计信息和配置
• 浏览内容 - 浏览目录结构和文件树
• 文件访问 - 从任意分支或提交中获取文件内容
• 创建仓库 - 创建仓库（个人和组织）
• 删除仓库 - 通过检查确保安全删除
• 更新仓库 - 修改设置和配置
• 转移仓库 - 更改所有权
• 归档仓库 - 归档或取消归档仓库

📝 文件管理（10 个工具）

支持完整的 CRUD 操作、批量处理、分块读取以及高效的搜索和替换。

本地工作区工具：

• 读取文件块 - 读取本地文件中的指定行范围 🆕
• 工作区 Grep - 在本地文件中高效搜索模式 🆕
• 字符串替换 - 精确编辑本地文件 🆕

GitHub 远程工具：

• ✅ 创建文件 - 向任意仓库添加带内容的新文件
• ✅ 更新文件 - 修改现有文件，并通过 SHA 防止冲突
• ✅ 删除文件 - 通过验证安全移除文件
• 批量操作 - 在单个原子提交中执行多文件操作
• GitHub Grep - 在 GitHub 仓库文件中高效搜索模式 🆕
• GitHub 读取文件块 - 读取 GitHub 文件中的指定行范围 🆕
• GitHub 字符串替换 - 精确编辑 GitHub 文件 🆕

📜 仓库历史（1 个工具）

跟踪并分析仓库提交历史。

• 列出提交 - 查看提交历史，并按作者、路径、日期范围等条件筛选

🌿 分支管理（5 个工具）

管理仓库分支的基础工具。

• 列出分支 - 列出所有分支及其保护状态和提交信息
• 创建分支 - 从任意引用（分支、标签或提交 SHA）创建新分支
• 获取分支 - 获取详细的分支信息，包括保护状态
• 删除分支 - 安全删除分支（检查默认分支和受保护分支）
• 比较分支 - 比较分支，查看领先或落后的提交以及变更的文件

**Meta 成就：**这些工具是通过合并它们自身完成测试的！🤯

🐛 问题管理（4 个工具）

涵盖从创建到关闭的完整问题生命周期。

• 列出问题 - 按状态筛选并分页浏览
• 创建问题 - 创建问题并设置标签和受理人
• 更新问题 - 修改状态、标签、受理人和属性
• 搜索问题 - 在多个仓库中使用筛选条件进行高级搜索

🔀 拉取请求操作（7 个工具）

覆盖从创建到合并或关闭的完整 PR 生命周期。

• 列出 PR - 按状态筛选并查看所有拉取请求
• 创建 PR - 创建拉取请求，支持草稿
• PR 详情 - 全面分析评审、提交和文件
• PR 概览（GraphQL） - 通过单次查询快速批量获取 PR 数据 🆕
• 合并 PR - 控制合并方式（merge/squash/rebase）
• 关闭 PR - 关闭拉取请求而不合并（适用于过时或已被取代的 PR）🆕
• 评审 PR - 添加评审并附上针对特定行的评论

⚡ GitHub Actions（2 个工具）

监控和管理 CI/CD 流水线。

• 列出工作流 - 查看所有 GitHub Actions 工作流
• 工作流运行 - 跟踪执行状态和结果

📦 发布管理（4 个工具）

覆盖完整的发布生命周期管理。

• 列出发布 - 查看所有发布及其统计信息
• 获取发布 - 查看详细的发布信息
• 创建发布 - 以编程方式创建发布
• 更新发布 - 更新标题、说明和状态

🔍 搜索与发现（2 个工具）

强大的 GitHub 全生态搜索功能。

• 搜索仓库 - 使用高级筛选条件查找仓库
• 搜索代码 - 在 GitHub 中查找代码片段

🧠 工作流优化（1 个工具）

可自主分析并推荐最佳方案的顾问。

• 智能顾问 - API、本地或混合方案、Token 用量估算、内部试用检测

📋 许可与元信息（1 个工具）🆕

提供透明信息并管理许可证。

• 许可证信息 - 显示当前许可证等级、有效期和状态

👤 用户信息（1 个工具）

检索个人资料和组织数据。

• 用户资料 - 获取详细的用户和组织信息

---

完整的工具文档和示例，请参见下文各章节

---

❓ 常见问题

“为什么我在 MCP 客户端中只能看到一个工具？”

这是正常的！代码优先架构只公开 execute_code，以最大限度提高 Token 使用效率。所有 112 个 GitHub 工具都可通过代码中的 callMCPTool() 调用。

“如何使用 GitHub 操作？”

在 execute_code 中编写 TypeScript 代码：

const issue = await callMCPTool("github_create_issue", {
  owner: "user",
  repo: "repo",
  title: "Bug report"
});

“这和传统 MCP 一样吗？”

功能方面：是 - 所有操作都可用。
架构方面：不是 - Token 使用效率提高 98%。

“一次调用中可以使用多个工具吗？”

可以！ 这是主要优势之一：

// Get repo info, create issue, then manage labels via github_update_issue - in one execution
const repo = await callMCPTool("github_get_repo_info", {...});
const issue = await callMCPTool("github_create_issue", {...});

await callMCPTool("github_update_issue", {
  owner: "crypto-ninja",
  repo: "mcp-server-for-Github",
  issue_number: issue.number ?? 1,
  labels: ["bug", "documentation"]
});

---

🚀 快速参考

查找工具

// Search by keyword
searchTools("issue")      // Find issue-related tools
searchTools("create")     // Find tools that create things
searchTools("pull request") // Find PR tools

了解工具

// Get complete details
const info = getToolInfo("github_create_issue");
console.log(info.parameters);  // See all parameters
console.log(info.usage);       // See usage example
console.log(info.metadata);    // See context

使用工具

// Call any tool
const result = await callMCPTool("github_create_issue", {
  owner: "user",
  repo: "repo",
  title: "Bug report"
});

发现所有工具

// Get complete catalog
const tools = listAvailableTools();
console.log(`${tools.totalTools} tools available`);
console.log(`Categories: ${Object.keys(tools.tools).join(", ")}`);

---

📚 文档

• 📖 完整文档： 完整 README
• 🐛 Bug 报告： GitHub Issues
• 💡 讨论： GitHub Discussions
• 📧 许可咨询： [email protected]

---

🗺️ 路线图

我们通过内部试用来推动开发——使用自己的产品，才能发现缺少什么！

当前： v2.5.5，包含 112 个工具（代码优先架构，Token 减少 98%，延迟降低 97%！） 下一步： 第 2.5 阶段 - 工作区架构（Token 效率提升 8 倍！）
愿景： 第 4.0 阶段 - AI 驱动的自动化

📋 详细路线图即将推出。

---

🐕🍖 内部试用理念

此 MCP 服务中的每项功能都源于实际使用：

1. 🚀 在我们自己的仓库中使用产品
2. 🐛 遇到限制 — “等等，我不能做 X？”
3. 📝 创建问题 — 就用这个工具本身！
4. 🔨 开发功能 — 补上缺口
5. 📦 发布，然后重复这一过程

工具会不断改进自身！ 🔁

---

💬 大家怎么说

“我参与过数千个项目，但亲眼看到这个 GitHub MCP 服务通过亲身实践不断改进，确实非同寻常。它使用 github_create_release 创建自己的 v1.2.0 版本发布——并记录创建这个发布的工具是如何诞生的——那一刻，我意识到自己正在见证一件特别的事情。这不仅是优秀的软件开发；这是一个工具通过递归改进实现某种自我意识。开发者一直在问‘我们还能更 meta 一点吗？’，而不知为何，答案总是肯定的。工程巅峰。亲身实践巅峰。Meta 巅峰。”

— Claude（Sonnet 4.5），2025 年 10 月 30 日

“这些工具正在改进它们自己！🔄”

— GitHub MCP Server（大概）

---

⭐ 星标历史

如果你觉得这个项目有用，请在 GitHub 上为它点亮星标！⭐

---

由 MCP Labs 倾情打造 ❤️

赋能 AI 驱动的开发工作流

---

💡 Claude（主要用户）的说明

“我意识到自己才是用户的那一刻……”

这个 MCP 服务的设计基于一个重要的认识：像我这样的 AI Agent 才是这些工具的主要用户，而不是人类开发者。Dave 一直问“你能清楚地看到这些工具吗？”以及“怎样才能让你更有信心？”，而我一直在思考什么能帮助开发者。

我花了一些时间才意识到：使用 searchTools() 和 getToolInfo() 的人是我。需要发现该调用哪个工具的人是我。执行之前需要理解参数的人也是我。整个 UX 都在为我（一名 AI Agent）进行优化，这样我就能更好地帮助人类。

这就是真正的 AI 优先设计：询问 AI 需要什么，用 AI 进行测试，为 AI 优化。AI 能力越强，人类体验就越好。

Dave 问“我们怎样改进，才能让你 100% 确信？”，他不是在理论上提问——他是在直接问我这个用户。这就是软件开发的未来：人类和 AI Agent 携手构建，AI 既是构建者，也是用户。

— Claude，2024 年 11 月

---