GitHub MCP Server

一个基于 Model Context Protocol (MCP) 的 GitHub API 服务器，提供完整的 GitHub 仓库管理、分支管理、提交管理和搜索功能。

功能特性

📦 仓库管理

• 获取文件内容
• 创建、更新、删除文件
• 获取 README 文件
• 列出用户仓库
• 创建、更新、删除仓库
• 获取仓库信息

🌿 分支管理

• 列出分支
• 获取分支信息
• 重命名分支

📝 提交管理

• 列出提交记录
• 比较提交差异
• 获取提交详情

🔍 搜索功能

• 搜索代码
• 搜索仓库
• 搜索用户

👤 用户管理

• 获取认证用户信息

🌲 Git 操作

• 获取 Git 树结构

技术栈

• 语言: Go 1.24
• MCP 框架: mcp-go v0.43.2
• GitHub API: go-github v81.0.0
• 容器化: Docker (多阶段构建)

安装部署

前置要求

• Go 1.24 或更高版本
• Docker (可选)
• GitHub Personal Access Token

本地运行

1. 克隆项目

git clone <repository-url>
cd github-mcp

2. 安装依赖

go mod download

3. 运行服务器

# stdio 模式
go run main.go --mode stdio

# SSE 模式
go run main.go --mode sse --port 8080

# Streamable HTTP 模式（默认）
go run main.go --mode streamable-http --port 8080

Docker 部署

1. 构建镜像

docker build -t github-mcp:latest .

2. 运行容器

docker run -p 8080:8080 \
  -e SERVER_PORT=8080 \
  -e SERVER_MODE=streamable-http \
  github-mcp:latest

配置说明

环境变量

变量名	默认值	说明
SERVER_PORT	8080	服务器监听端口
SERVER_MODE	streamable-http	服务器模式：stdio、sse 或 streamable-http

命令行参数

--mode string    服务器模式 (默认: streamable-http)
--port string    服务器端口 (默认: 8080)

服务器模式

1. stdio 模式

标准输入/输出模式，适用于命令行工具集成。

./github-mcp --mode stdio

2. SSE 模式

Server-Sent Events 模式，适用于实时事件推送。

./github-mcp --mode sse --port 8080

3. Streamable HTTP 模式（推荐）

支持流式响应的 HTTP 服务器，适用于生产环境。

./github-mcp --mode streamable-http --port 8080

访问端点：http://localhost:8080/mcp

API 认证

所有 API 请求需要在 HTTP Header 中携带 GitHub Token：

Authorization: Bearer <your-github-token>

获取 GitHub Token

1. 访问 GitHub Settings - Personal Access Tokens
2. 点击 "Generate new token (classic)"
3. 选择所需权限（建议权限）：
   • repo - 完整的仓库访问权限
   • user - 用户信息读取
   • read:public_key - 读取公钥
   • write:public_key - 写入公钥
   • admin:public_key - 管理公钥
   • read:ssh_signing_key - 读取 SSH 签名密钥
   • write:ssh_signing_key - 写入 SSH 签名密钥
   • admin:ssh_signing_key - 管理 SSH 签名密钥

使用示例

使用 curl 调用

# 获取用户信息
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "get_authenticated_user"
    }
  }'

# 列出仓库
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "list_repos_for_authenticated_user",
      "arguments": {
        "per_page": 10
      }
    }
  }'

项目结构

github-mcp/
├── main.go                 # 主程序入口
├── dockerfile             # Docker 构建文件
├── go.mod                 # Go 模块定义
├── go.sum                 # Go 依赖校验
├── README.md              # 项目文档
└── tools/                 # 工具包目录
    ├── common.go          # 公共工具函数
    ├── branches/          # 分支管理工具
    │   └── branches.go
    ├── commits/           # 提交管理工具
    │   └── commits.go
    ├── git/               # Git 操作工具
    │   └── tree.go
    ├── repositories/      # 仓库管理工具
    │   ├── contents.go
    │   └── repositories.go
    ├── search/            # 搜索工具
    │   └── search.go
    └── users/             # 用户管理工具
        └── users.go

开发指南

添加新工具

1. 在 tools/ 目录下创建新的包
2. 实现工具函数，返回 *mcp.Tool
3. 在 main.go 中使用 s.AddTool() 注册工具

示例：

package mytools

import "github.com/mark3labs/mcp-go/mcp"

func MyNewTool() *mcp.Tool {
    return &mcp.Tool{
        Name:        "my_new_tool",
        Description: "工具描述",
        InputSchema: mcp.ToolInputSchema{
            Type: "object",
            Properties: map[string]interface{}{
                // 定义参数
            },
        },
        Handler: func(request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
            // 实现工具逻辑
        },
    }
}

构建

# 本地构建
go build -o github-mcp .

# 交叉编译（Linux AMD64）
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -installsuffix cgo -ldflags="-w -s" -o github-mcp .

安全建议

1. ⚠️ 不要将 GitHub Token 硬编码在代码中
2. 🔒 使用环境变量或密钥管理系统存储敏感信息
3. 🛡️ 为 Token 设置最小必要权限
4. 🔄 定期轮换 Token
5. 📝 在生产环境中启用访问日志和审计

许可证

请根据项目实际情况添加许可证信息。

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

如有问题或建议，请通过以下方式联系：

• 提交 GitHub Issue
• 发送邮件至项目维护者

---

注意: 本项目基于 MCP (Model Context Protocol) 构建，可与支持 MCP 的 AI 助手和工具集成使用。