GitHub MCP Client for Docker GMU Server

Docker GMU 服务的 GitHub MCP 客户端

这是一个 MCP（Model Context Protocol）客户端，可连接到在 Docker 中运行的 GitHub 多用户服务（GMU），并提供由 Claude 驱动的 GitHub 操作交互界面。

功能

• 🐳 Docker 集成：连接到在 Docker 容器中运行的 GMU 服务
• 🤖 AI 驱动：使用 Claude 解读自然语言查询并调用相应的 GitHub 工具
• 🔐 多用户支持：每个请求都使用对应用户的 GitHub Personal Access Token
• 🛠️ 完整的 GitHub API：访问仓库、议题、拉取请求、用户、搜索等功能
• 💬 交互式聊天：通过自然语言界面执行 GitHub 操作

先决条件

1. Docker 和 Docker Compose：GMU 服务必须在 Docker 中运行
2. Python 3.13+：用于运行 MCP 客户端
3. GitHub Personal Access Token：用于通过 GitHub API 进行身份验证
4. Anthropic API Key：用于集成 Claude

快速设置

1. 安装依赖项

# Using uv (recommended)
uv add mcp anthropic python-dotenv

2. 配置环境变量

在项目根目录下创建一个 .env 文件：

# GitHub Personal Access Token
# Get this from: https://github.com/settings/tokens
GITHUB_TOKEN=ghp_your_github_personal_access_token_here

# Anthropic API Key for Claude
# Get this from: https://console.anthropic.com/
ANTHROPIC_API_KEY=sk-ant-your_anthropic_api_key_here

3. 启动 GMU 服务

# Start the GitHub Multi-User Server in Docker
docker-compose up -d

# Verify it's running
docker ps | grep github-mcp-server-multiuser

使用方法

测试连接

首先，验证一切是否正常运行：

python test_gmu_connection.py

此全面测试将：

• ✅ 测试与 GMU 服务的 MCP 连接
• ✅ 验证 GitHub Token 功能（如已提供）
• ✅ 测试 Claude 集成
• ✅ 列出所有可用的 GitHub 工具

交互式 MCP 客户端

运行主交互式客户端：

python tests/test_gmu.py

客户端将：

1. 提示输入 GitHub Token（如果环境中未设置）
2. 连接到在 Docker 中运行的 GMU 服务
3. 启动交互式聊天界面

命令示例

进入交互模式后，可以使用自然语言：

❓ Query: Get my GitHub user information
❓ Query: List my repositories
❓ Query: how many repos I have
❓ Query: Search for Python repositories with more than 1000 stars
❓ Query: Create an issue in my test repository
❓ Query: List open pull requests in microsoft/vscode
❓ Query: tools (to see all available GitHub tools)
❓ Query: quit (to exit)

可用的 GitHub 工具

GMU 服务提供全面的 GitHub 功能：

• 用户操作：获取用户信息、搜索用户
• 仓库操作：列出仓库、获取内容、创建/更新文件、创建分支
• 议题管理：创建、更新、列出议题以及对议题发表评论
• 拉取请求操作：创建、审查、合并 PR，以及获取文件/差异
• 搜索：搜索仓库、议题、代码、用户
• 以及更多……

在交互模式下输入 tools，即可查看完整的 41 个可用工具列表。

架构

┌─────────────────┐    MCP Protocol    ┌──────────────────┐    GitHub API    ┌─────────────┐
│   MCP Client    │◄──────────────────►│  GMU Server      │◄─────────────────►│   GitHub    │
│ (test_gmu.py)   │                    │  (Docker)        │                  │             │
│                 │                    │                  │                  │             │
└─────────────────┘                    └──────────────────┘                  └─────────────┘
         │                                       │
         │ Anthropic API                         │ 
         ▼                                       │
┌─────────────────┐                             │
│     Claude      │                             │ Per-request auth
│   (Anthropic)   │                             │ with GitHub tokens
└─────────────────┘                             ▼
                                      ┌──────────────────┐
                                      │  GitHub Tools    │
                                      │ (Multi-tenancy)  │
                                      └──────────────────┘

工作原理

1. 连接：MCP 客户端使用 docker exec 连接到在 Docker 中运行的 GMU 服务
2. 身份验证：每次 GitHub API 调用都会包含一个对应请求的 auth_token 参数
3. 查询处理：用户查询会与可用的 GitHub 工具一起发送给 Claude
4. 工具执行：Claude 决定调用哪些 GitHub 工具，并通过 MCP 执行
5. 响应：将结果整理后显示给用户

故障排除

容器未运行

Error: Container 'github-mcp-server-multiuser' is not running.
Please start the container with: docker-compose up -d

解决方案：启动 Docker 容器：

docker-compose up -d

缺少 GitHub Token

🔑 GitHub Personal Access Token required

解决方案：

1. 在 https://github.com/settings/tokens 创建 GitHub Personal Access Token
2. 将其添加到 .env 文件，或设置 GITHUB_TOKEN 环境变量

缺少 Anthropic API Key

Error: ANTHROPIC_API_KEY environment variable is required

解决方案：

1. 从 https://console.anthropic.com/ 获取 API Key
2. 将其作为 ANTHROPIC_API_KEY 添加到 .env 文件

JSON 序列化错误

最新版本包含对 MCP 内容类型的稳健处理，可防止序列化错误。

MCP 连接问题

Error connecting to GMU server: ...

解决方案：

1. 验证 Docker 正在运行：docker ps
2. 查看容器日志：docker-compose logs github-mcp-server
3. 重启容器：docker-compose restart

开发

项目结构

├── tests/
│   └── test_gmu.py              # Main MCP client
├── test_gmu_connection.py       # Comprehensive connection tests
├── docker-compose.yaml          # GMU server configuration
├── pyproject.toml              # Project configuration
└── README.md                   # This file

参与贡献

1. Fork 此仓库
2. 创建功能分支
3. 使用 GMU 服务进行测试：python test_gmu_connection.py
4. 测试交互式客户端：python tests/test_gmu.py
5. 提交拉取请求

许可证

本项目遵循与 GitHub MCP Server Multi-User 相同的许可证。