GitHub MCP Server

GitHub MCP Server v4.0

基于 Go 的 MCP 服务，可将 GitHub 连接到 Claude Desktop，从而通过 Claude 的界面直接操作仓库。

**工具：**26 个整合工具（85 项操作） | **架构：**混合（本地 Git + GitHub API + 管理控制）

v4.0 新增内容

• 整合工具设计：85 项操作整合到仅 26 个工具中，避免因工具数量限制造成 AI 混淆
• 操作参数模式：每个工具都接受一个 operation 参数，用于选择具体操作
• --toolsets 标志：启动服务时仅开放选定的工具组（git、github、admin、files）
• 真正的自动备份：当 enable_auto_backup: true 时，在执行 HIGH/CRITICAL 操作前写入 JSON 备份
• 4 级安全系统：风险分类（LOW/MEDIUM/HIGH/CRITICAL），并提供确认令牌
• 22 项管理操作：仓库设置、分支保护、webhook、协作者和团队
• 审计日志：基于 JSON 的操作跟踪，并自动轮换

所需的令牌权限

最低要求

repo        - Full control of private repositories (essential)

可选（完整功能所需）

security_events  - For dismissing security alerts
workflow         - For re-running GitHub Actions workflows
admin:repo_hook  - Enhanced webhook management
admin:org        - For team management in organizations

生成令牌

1. 前往：GitHub 设置 > Personal Access Tokens
2. 点击“Generate new token (classic)”
3. 选择所需的作用域
4. 复制生成的令牌

安装

# Install dependencies
go mod tidy

# Compile (using included script)
.\compile.bat          # Windows
./build-mac.bat        # macOS cross-compile

# Or compile manually
go build -o github-mcp-server-v4.exe ./cmd/github-mcp-server/

测试

# Run all tests
go test ./...

# Run tests with verbose output
go test ./... -v

# Run tests for a specific package
go test ./pkg/git/ -v
go test ./pkg/safety/ -v

Claude Desktop 配置

多配置文件（推荐）

{
  "mcpServers": {
    "github-personal": {
      "command": "C:\\path\\to\\github-mcp-server-v4.exe",
      "args": ["--profile", "personal"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_token"
      }
    },
    "github-work": {
      "command": "C:\\path\\to\\github-mcp-server-v4.exe",
      "args": ["--profile", "work"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_work_token"
      }
    }
  }
}

基本配置（单个令牌）

{
  "mcpServers": {
    "github-mcp": {
      "command": "C:\\path\\to\\github-mcp-server-v4.exe",
      "args": [],
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

工具组筛选（可选）

仅开放特定工具组，以缩小攻击面：

{
  "args": ["--toolsets", "git,github"]
}

可用组：git（14 个工具）、github（4 个工具）、admin（4 个工具）、files（4 个工具）。默认值为 all。

可用工具（26 个）

工具使用 operation 参数，在一个名称下提供多项操作。这会将工具数量从 85 个减少到 26 个，避免 AI 模型混淆。

Git 信息（2 个工具）

工具	操作
git_info	status、file_sha、last_commit、file_content、changed_files、validate_repo、list_files、context、validate_clean
git_set_workspace	为所有 Git 操作设置工作目录

Git 基本操作（3 个工具）

工具	描述
git_init	初始化新的 Git 仓库
git_add	将文件暂存以便提交
git_commit	提交暂存的更改

Git 高级操作（9 个工具）

工具	操作
git_history	log、diff
git_branch	checkout、checkout_remote、list、merge、rebase、backup
git_sync	push、pull、force_push、push_upstream、sync、pull_strategy
git_conflict	status、resolve、detect、safe_merge
git_stash	list、push、pop、apply、drop、clear
git_remote	list、add、remove、show、fetch
git_tag	list、create、delete、push、show
git_clean	untracked、untracked_dirs、ignored、all
git_reset	撤销提交（soft/mixed/hard）

混合（3 个工具）

工具	描述
gh_create_file	创建文件——优先使用 Git，失败时回退到 GitHub API
gh_update_file	更新文件——优先使用 Git，失败时回退到 GitHub API
gh_push_files	一次调用中写入多个文件，并执行 git add/commit/push

GitHub API（1 个工具）

工具	操作
github_repo	list_repos、create_repo、list_prs、create_pr

仪表板（1 个工具）

工具	操作
github_dashboard	full、notifications、issues、prs_review、security、workflows、mark_read

响应（1 个工具）

工具	操作
github_respond	comment_issue、comment_pr、review_pr

修复（1 个工具）

工具	操作
github_repair	close_issue、merge_pr、rerun_workflow、dismiss_alert

管理（4 个工具）

工具	操作	风险
github_admin_repo	get_settings、update_settings、archive、delete	LOW → CRITICAL
github_branch_protection	get、update、delete	LOW → CRITICAL
github_webhooks	list、create、update、delete、test	LOW → HIGH
github_collaborators	list、check、add、update_permission、remove、list_invitations、accept_invitation、cancel_invitation、list_teams、add_team	LOW → HIGH

文件操作（1 个工具）

工具	操作
github_files	list、download、download_repo、pull_repo

安全系统

4 级风险分类

等级	说明	行为（moderate 模式）
LOW	只读	直接执行
MEDIUM	可撤销的更改	可选试运行
HIGH	影响协作	需要确认令牌
CRITICAL	不可逆	令牌 + 备份建议

安全系统使用复合键 tool:operation（例如 github_webhooks:delete）进行风险分类。

安全模式

模式	需要确认的级别	推荐用途
strict	MEDIUM+	关键生产环境
moderate	HIGH+	一般用途（默认）
permissive	CRITICAL	本地开发
disabled	从不	不推荐

安全配置

在可执行文件旁创建 safety.json（可选）：

{
  "mode": "moderate",
  "enable_audit_log": true,
  "require_confirmation_above": 3,
  "audit_log_path": "./mcp-admin-audit.log",
  "audit_log_max_size_mb": 10,
  "audit_log_max_backups": 5
}

如果 safety.json 不存在，则默认使用 moderate 模式，并启用审计日志记录。

无 Git 模式

在未安装 Git 的系统上，服务会：

1. 自动检测 Git 是否缺失
2. 从工具列表中筛除 git_* 工具
3. 保留所有 API、管理、仪表板和文件操作工具正常运行
4. 尝试使用 Git 工具时返回友好错误信息

github_files 工具（list、download、download_repo、pull_repo）可仅使用 GitHub API 克隆和更新仓库，无需 Git。

安全

• 防止所有 Git 操作中的命令注入
• 防止路径遍历
• 防止 Webhook URL 中的 SSRF
• 为破坏性操作提供加密确认令牌
• 记录所有管理操作的审计日志

如需报告漏洞，请参阅我们的安全策略。

系统要求

• Go：1.26.6 或更高版本
• Git：可选（自动检测；文件/API 工具无需 Git 即可使用）
• github.com/google/go-github v88.0.0
• golang.org/x/oauth2 v0.36.0
• GitHub Token：最低需要 repo 权限

项目状态

• 26 个整合工具，提供 85 项操作
• 混合式本地 Git + GitHub API 系统
• 4 级安全系统，配备确认令牌和自动备份
• 支持多配置文件
• 完整的测试套件
• 可用于生产环境（v4.0）

更新日志：完整的更改历史请参阅 CHANGELOG.md。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

许可证

MIT 许可证 — 详情请参阅 LICENSE。