@itkmoon/github-mcp

v1.0.0

Published

14 days ago

GitHub MCP Server - A complete GitHub toolkit for Model Context Protocol

0High
0Medium
0Low

unigle

mcp github model-context-protocol octokit

GitHub MCP Tool

✨ 功能特性

14 个 MCP Tools：覆盖仓库管理、Issue 管理、PR 管理和代码操作四大场景
基于 Octokit：使用官方 GitHub REST API 客户端，稳定可靠
Zod 参数校验：所有工具参数经过严格类型校验，提前拦截非法输入
Stdio 模式：支持 Claude Desktop、Cursor、Trae 等 AI 客户端直接集成
企业版支持：可通过 GITHUB_API_URL 连接 GitHub Enterprise
TypeScript 全栈：完整的类型定义，开发体验友好

📦 安装

方式一：npm 全局安装（推荐）

npm install -g @itkmoon/github-mcp

方式二：GitHub 克隆

git clone https://github.com/ITKMUnigle/GitHub-MCP-Tool.git
cd GitHub-MCP-Tool
npm install
npm run build

⚙️ 配置

Claude Desktop 配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "github-mcp": {
      "command": "npx",
      "args": ["-y", "@itkmoon/github-mcp"],
      "env": {
        "GITHUB_TOKEN": "your_github_personal_access_token_here"
      }
    }
  }
}

Cursor 配置

在 Cursor 设置中添加以下 MCP Server 配置：

{
  "mcpServers": {
    "github-mcp": {
      "command": "npx",
      "args": ["-y", "@itkmoon/github-mcp"],
      "env": {
        "GITHUB_TOKEN": "your_github_personal_access_token_here"
      }
    }
  }
}

路径: Settings → MCP → Add MCP Server → 输入配置 JSON

Trae 配置

在 Trae 的 MCP 设置中添加：

{
  "mcpServers": {
    "github-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@itkmoon/github-mcp"],
      "env": {
        "GITHUB_TOKEN": "your_github_personal_access_token_here"
      }
    }
  }
}

路径: 设置 → MCP Servers → 添加服务器

🌍 环境变量说明

| 变量名 | 必填 | 说明 | 示例 | |--------|------|------|------| | GITHUB_TOKEN | ✅ 是 | GitHub Personal Access Token (Classic 或 Fine-grained) | ghp_xxxxxxxxxxxx | | GITHUB_API_URL | ❌ 否 | 自定义 GitHub API 地址（用于 GitHub Enterprise） | https://github.example.com/api/v3 |

快速设置 Token

# Linux / macOS
export GITHUB_TOKEN=your_token_here

# Windows (PowerShell)
$env:GITHUB_TOKEN = "your_token_here"

# Windows (CMD)
set GITHUB_TOKEN=your_token_here

也可复制 .env.example 为 .env 并填入实际值：

cp .env.example .env
# 编辑 .env 文件，填入 GITHUB_TOKEN

🛠️ 工具详细说明

一、仓库管理类（4 个）

| 工具名 | 描述 | 参数 | 返回值 | 示例 | |--------|------|------|--------|------| | github_create_repo | 创建新的 GitHub 仓库 | name (必填, string): 仓库名称description (可选, string): 描述private (可选, boolean): 是否私有，默认 falseautoInit (可选, boolean): 是否初始化 README，默认 false | 仓库完整信息 (id, full_name, html_url 等) | 创建公开仓库: {"name": "my-new-repo"}创建私有仓库: {"name": "private-repo", "private": true, "description": "私密项目", "autoInit": true} | | github_list_repos | 列出用户的 GitHub 仓库 | username (可选, string): 用户名type (可选, enum): all/owner/member，默认 ownersort (可选, enum): updated/created/pushed/full_name，默认 updated | 仓库列表 (name, description, url, stars, forks 等) | 列出自己的仓库: {}列出某用户所有仓库: {"username": "octocat", "type": "all", "sort": "updated"} | | github_get_repo | 获取仓库详细信息 | owner (必填, string): 仓库所有者repo (必填, string): 仓库名称 | 仓库详情 (基本信息、统计、许可证、时间戳等) | {"owner": "ITKMUnigle", "repo": "GitHub-MCP-Tool"} | | github_delete_repo | ⚠️ 删除指定仓库（危险操作） | owner (必填, string): 仓库所有者repo (必填, string): 仓库名称 | 操作结果 + 警告信息 | {"owner": "myuser", "repo": "old-repo"} |

二、Issue 管理类（4 个）

| 工具名 | 描述 | 参数 | 返回值 | 示例 | |--------|------|------|--------|------| | github_create_issue | 创建新的 Issue | owner (必填, string): 仓库所有者repo (必填, string): 仓库名称title (必填, string): 标题 (1-256字符)body (可选, string): 内容labels (可选, string[]): 标签列表assignees (可选, string[]): 负责人列表 | Issue 信息 (number, title, url, labels 等) | {"owner": "ITKMUnigle", "repo": "GitHub-MCP-Tool", "title": "Bug: 无法连接", "body": "详细描述...", "labels": ["bug", "high-priority"], "assignees": ["developer1"]} | | github_list_issues | 列出仓库的 Issues | owner (必填, string): 仓库所有者repo (必填, string): 仓库名称state (可选, enum): open/closed/all，默认 openlabels (可选, string[]): 按标签筛选sort (可选, enum): created/updated/comments，默认 created | Issue 列表 (自动过滤 PR，仅显示纯 Issue) | {"owner": "ITKMUnigle", "repo": "GitHub-MCP-Tool", "state": "open", "sort": "updated"} | | github_update_issue | 更新 Issue 状态或内容 | owner (必填, string): 仓库所有者repo (必填, string): 仓库名称issueNumber (必填, number): Issue 编号title (可选, string): 新标题body (可选, string): 新内容state (可选, enum): open/closedlabels (可选, string[]): 新标签assignees (可选, string[]): 新负责人 | 更新后的 Issue 信息 | 关闭 Issue: {"owner": "ITKMUnigle", "repo": "GitHub-MCP-Tool", "issueNumber": 42, "state": "closed"}更新标题和标签: {"issueNumber": 42, "title": "新标题", "labels": ["enhancement"]} | | github_add_comment | 在 Issue 或 PR 下添加评论 | owner (必填, string): 仓库所有者repo (必填, string): 仓库名称issueNumber (必填, number): Issue/PR 编号body (必填, string): 评论内容 (最大65536字符) | 评论信息 (id, body, url, created_at) | {"owner": "ITKMUnigle", "repo": "GitHub-MCP-Tool", "issueNumber": 42, "body": "已确认该问题，正在修复中..."} |

三、Pull Request 管理类（3 个）

| 工具名 | 描述 | 参数 | 返回值 | 示例 | |--------|------|------|--------|------| | github_create_pr | 创建新的 Pull Request | owner (必填, string): 仓库所有者repo (必填, string): 仓库名称title (必填, string): PR 标题 (1-256字符)head (必填, string): 源分支名base (必填, string): 目标分支名body (可选, string): PR 描述 | PR 信息 (number, title, review_url, additions/deletions 等) | {"owner": "ITKMUnigle", "repo": "GitHub-MCP-Tool", "title": "feat: 新增搜索功能", "head": "feature/search", "base": "main", "body": "## 变更摘要\n- 新增代码搜索工具..."} | | github_list_prs | 列出仓库的 Pull Requests | owner (必填, string): 仓库所有者repo (必填, string): 仓库名称state (可选, enum): open/closed/all，默认 opensort (可选, enum): created/updated，默认 created | PR 列表 (含分支信息、冲突状态、代码变更统计) | {"owner": "ITKMUnigle", "repo": "GitHub-MCP-Tool", "state": "open", "sort": "updated"} | | github_merge_pr | 合并指定的 Pull Request | owner (必填, string): 仓库所有者repo (必填, string): 仓库名称prNumber (必填, number): PR 编号mergeMethod (可选, enum): merge/squash/rebase，默认 merge | 合并结果 (merged_sha, method, timestamp) | Squash 合并: {"owner": "ITKMUnigle", "repo": "GitHub-MCP-Tool", "prNumber": 12, "mergeMethod": "squash"}Rebase 合并: {"prNumber": 12, "mergeMethod": "rebase"} |

四、代码操作类（3 个）

| 工具名 | 描述 | 参数 | 返回值 | 示例 | |--------|------|------|--------|------| | github_read_file | 读取仓库中指定文件的内容 | owner (必填, string): 仓库所有者repo (必填, string): 仓库名称path (必填, string): 文件路径ref (可选, string): 分支/commit SHA，默认 main | 文件信息 + Base64 解码后的内容 (大文件自动截断至 ~50KB) | 读取 README: {"owner": "ITKMUnigle", "repo": "GitHub-MCP-Tool", "path": "README.md"}读取特定版本: {"path": "src/index.ts", "ref": "v1.0.0"} | | github_search_code | 在 GitHub 上搜索代码 | query (必填, string): 搜索关键词 (至少3字符)language (可选, string): 编程语言筛选perPage (可选, number): 每页数量 (1-100)，默认 10 | 搜索结果 (total_count, 匹配片段, 仓库/路径信息) | 搜索函数: {"query": "createRepo repo:ITKMUnigle/GitHub-MCP-Tool"}按语言搜索: {"query": "MCP server", "language": "typescript", "perPage": 20} | | github_list_commits | 列出仓库的提交历史 | owner (必填, string): 仓库所有者repo (必填, string): 仓库名称branch (可选, string): 分支名，默认 mainperPage (可选, number): 每页数量 (1-100)，默认 10 | 提交列表 (短 SHA、消息、作者、日期) | {"owner": "ITKMUnigle", "repo": "GitHub-MCP-Tool", "branch": "main", "perPage": 20}查看 dev 分支: {"branch": "develop"} |

🧪 连接测试

用例一：Stdio 模式测试

步骤 1：配置环境变量

# Linux/macOS
export GITHUB_TOKEN=ghp_your_actual_token

# Windows PowerShell
$env:GITHUB_TOKEN = "ghp_your_actual_token"

步骤 2：启动 MCP Server

# 使用全局安装的命令
github-mcp

# 或使用 npx 直接运行
npx -y @itkmoon/github-mcp

# 或从源码运行
npm run start:stdio

步骤 3：预期输出

终端应显示：

🚀 GitHub MCP Server v1.0.0 正在启动...
📋 已注册 14 个工具
✅ GitHub MCP Server 已就绪，等待连接...

步骤 4：AI 客户端验证

在 Claude Desktop / Cursor / Trae 中发送以下消息测试：

请帮我列出 ITKMUnigle 用户的前5个公开仓库

预期输出：AI 应调用 github_list_repos 工具并以结构化 JSON 格式返回仓库列表。

用例二：API 直接调用测试

使用 curl 通过 GitHub API 验证 Token 有效性和各端点功能：

# ===== 基础验证：检查 Token 有效性 =====
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/user

# 预期输出：返回认证用户信息 JSON（含 login, id, name 等字段）

# ===== 测试创建仓库 =====
curl -X POST -H "Authorization: token $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/user/repos \
  -d '{"name":"mcp-test-repo","description":"MCP 测试仓库","private":true}'

# 预期输出：返回新创建仓库的完整 JSON（含 html_url, clone_url 等）

# ===== 测试列出 Issues =====
curl -H "Authorization: token $GITHUB_TOKEN" \
  "https://api.github.com/repos/ITKMUnigle/GitHub-MCP-Tool/issues?state=open&per_page=5"

# 预期输出：返回开放 Issue 列表 JSON 数组

# ===== 测试列出 PRs =====
curl -H "Authorization: token $GITHUB_TOKEN" \
  "https://api.github.com/repos/ITKMUnigle/GitHub-MCP-Tool/pulls?state=open&per_page=5"

# 预期输出：返回开放 PR 列表 JSON 数组

# ===== 测试读取文件 =====
curl -H "Authorization: token $GITHUB_TOKEN" \
  "https://api.github.com/repos/ITKMUnigle/GitHub-MCP-Tool/contents/package.json"

# 预期输出：返回文件的 content (Base64编码)、sha、size 等信息

# ===== 测试搜索代码 =====
curl -H "Authorization: token $GITHUB_TOKEN" \
  "https://api.github.com/search/code?q=createRepo+repo:ITKMUnigle/GitHub-MCP-Tool&per_page=5"

# 预期输出：返回搜索结果（含 total_count, items 数组及 text_matches 片段）

# ===== 测试获取提交历史 =====
curl -H "Authorization: token $GITHUB_TOKEN" \
  "https://api.github.com/repos/ITKMUnigle/GitHub-MCP-Tool/commits?per_page=5"

# 预期输出：返回提交记录数组（含 sha, commit.message, author 等）

🏗️ 架构图

graph TB
    subgraph ClientLayer["🎨 第一层：AI 客户端"]
        C1["Claude Desktop"]
        C2["Cursor"]
        C3["Trae IDE"]
        C4["其他 MCP 客户端"]
    end

    subgraph MCPLayer["⚙️ 第二层：MCP Server (本工具)"]
        M1["Server 入口 (server.ts)"]
        M2["路由分发 (14 个 Tool Handler)"]
        M3["参数校验 (Zod Schema)"]
    end

    subgraph ServiceLayer["🔧 第三层：服务层"]
        S1["GitHubService (github.service.ts)"]
        S2["Token 认证管理"]
        S3["错误处理与格式化"]
    end

    subgraph APILayer["🌐 第四层：GitHub API (Octokit)"]
        A1["REST API v3"]
        A2["Repos / Issues / PRs"]
        A3["Search / Git Data"]
    end

    ClientLayer -->|"Stdio Transport<br>(JSON-RPC)"| MCPLayer
    MCPLayer -->|"业务逻辑调用"| ServiceLayer
    ServiceLayer -->|"HTTP 请求<br>(OAuth Bearer)"| APILayer

    classDef clientStyle fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
    classDef mcpStyle fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1
    classDef serviceStyle fill:#fff3e0,stroke:#ef6c00,stroke-width:2px,color:#e65100
    classDef apiStyle fill:#fce4ec,stroke:#c62828,stroke-width:2px,color:#b71c1c

    class C1,C2,C3,C4 clientStyle
    class M1,M2,M3 mcpStyle
    class S1,S2,S3 serviceStyle
    class A1,A2,A3 apiStyle

🔑 GitHub Token 获取指南

步骤 1：打开 Token 设置页面

访问 GitHub Settings > Personal Access Tokens

步骤 2：选择 Token 类型

推荐选择 Fine-grained tokens（细粒度权限），如需兼容旧版 API 可选 Classic tokens

步骤 3：配置 Token 权限

Fine-grained Token 所需权限：

| 权限类别 | 所需权限级别 | 说明 | |----------|-------------|------| | Repository permissions | Read and Write (Contents, Issues, Pull Requests, Metadata) | 读写仓库内容、Issue 和 PR | | Account permissions | Read-only (Members) | 读取组织成员信息 |

Classic Token 所需范围（Scopes）：

| Scope | 说明 | |-------|------| | repo | 完整仓库访问（必需） | | read:org | 读取组织成员（可选） | | gist | 创建 Gist（可选） |

步骤 4：生成并保存 Token

点击 Generate token 按钮
立即复制 生成的 Token（只显示一次！）
将 Token 粘贴到配置文件的环境变量中

⚠️ 重要提示：Token 仅在生成时显示一次，离开页面后无法再次查看。请妥善保管。

🔒 安全注意事项

Token 保管
- ❌ 不要将 Token 提交到代码仓库（已通过 .gitignore 排除 .env）
- ❌ 不要在日志、聊天或公开场合分享 Token
- ✅ 使用系统环境变量或安全的密钥管理服务存储
- ✅ 定期轮换 Token（建议每 90 天更换一次）
权限最小化原则
- Fine-grained Token：仅授予必要的仓库和操作权限
- Classic Token：勾选最小必要的 Scopes
- 避免使用具有 admin 或 delete 权限的 Token 进行日常操作
危险操作警告
- github_delete_repo 为危险操作，执行前会输出 ⚠️ 警告日志
- 此操作不可撤销，删除后数据无法恢复
- 建议在生产环境中谨慎使用删除相关工具
网络安全
- 本工具通过 HTTPS 与 GitHub API 通信
- API 请求超时设置为 30 秒，防止长时间挂起
- 支持 GitHub Enterprise 自定义 API 端点（内网部署场景）
输入校验
- 所有参数均通过 Zod Schema 进行严格校验
- 限制字符串长度、数值范围，防止注入攻击
- 仓库名称仅允许字母、数字、点、下划线和连字符

📄 许可证

本项目基于 MIT License 开源发布。

MIT License

Copyright (c) 2026 unigle ([email protected])

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

🔗 相关链接

| 链接 | 地址 | |------|------| | 🏠 GitHub 仓库 | https://github.com/ITKMUnigle/GitHub-MCP-Tool | | 📦 npm 包 | https://www.npmjs.com/package/@itkmoon/github-mcp | | 📖 MCP 规范 | https://modelcontextprotocol.io | | 🐙 Octokit 文档 | https://octokit.github.io/rest.js/v19 | | 🐛 问题反馈 | https://github.com/ITKMUnigle/GitHub-MCP-Tool/issues |

English Version | Made with ❤️ by unigle