GitHub MCP Client for Docker GMU Server

This is an MCP (Model Context Protocol) client that connects to the GitHub Multi-User Server (GMU) running in Docker and provides an interactive interface for GitHub operations powered by Claude.

Features

• 🐳 Docker Integration: Connects to GMU server running in Docker container
• 🤖 AI-Powered: Uses Claude to interpret natural language queries and call appropriate GitHub tools
• 🔐 Multi-User Support: Each request uses per-user GitHub Personal Access Tokens
• 🛠️ Full GitHub API: Access repos, issues, pull requests, users, search, and more
• 💬 Interactive Chat: Natural language interface for GitHub operations

Prerequisites

1. Docker & Docker Compose: The GMU server must be running in Docker
2. Python 3.13+: For running the MCP client
3. GitHub Personal Access Token: For authenticating with GitHub API
4. Anthropic API Key: For Claude integration

Quick Setup

1. Install Dependencies

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

2. Configure Environment Variables

Create a .env file in the project root:

# 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. Start the GMU Server

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

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

Usage

Test Connection

First, verify everything is working:

python test_gmu_connection.py

This comprehensive test will:

• ✅ Test MCP connection to GMU server
• ✅ Verify GitHub token functionality (if provided)
• ✅ Test Claude integration
• ✅ List all available GitHub tools

Interactive MCP Client

Run the main interactive client:

python tests/test_gmu.py

The client will:

1. Prompt for your GitHub token (if not in environment)
2. Connect to the GMU server running in Docker
3. Start an interactive chat interface

Example Commands

Once in the interactive mode, you can use natural language:

❓ 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)

Available GitHub Tools

The GMU server provides access to comprehensive GitHub functionality:

• User Operations: Get user info, search users
• Repository Operations: List repos, get contents, create/update files, create branches
• Issue Management: Create, update, list, comment on issues
• Pull Request Operations: Create, review, merge PRs, get files/diffs
• Search: Search repositories, issues, code, users
• And much more...

Type tools in the interactive mode to see the complete list of 41 available tools.

Architecture

┌─────────────────┐    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)  │
                                      └──────────────────┘

How It Works

1. Connection: The MCP client connects to the GMU server running in Docker using docker exec
2. Authentication: Each GitHub API call includes a per-request auth_token parameter
3. Query Processing: User queries are sent to Claude along with available GitHub tools
4. Tool Execution: Claude determines which GitHub tools to call and executes them via MCP
5. Response: Results are formatted and displayed to the user

Troubleshooting

Container Not Running

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

Solution: Start the Docker container:

docker-compose up -d

Missing GitHub Token

🔑 GitHub Personal Access Token required

Solution:

1. Create a GitHub Personal Access Token at https://github.com/settings/tokens
2. Add it to your .env file or set the GITHUB_TOKEN environment variable

Missing Anthropic API Key

Error: ANTHROPIC_API_KEY environment variable is required

Solution:

1. Get an API key from https://console.anthropic.com/
2. Add it to your .env file as ANTHROPIC_API_KEY

JSON Serialization Errors

The latest version includes robust handling of MCP content types to prevent serialization errors.

MCP Connection Issues

Error connecting to GMU server: ...

Solution:

1. Verify Docker is running: docker ps
2. Check container logs: docker-compose logs github-mcp-server
3. Restart the container: docker-compose restart

Development

Project Structure

├── 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

Contributing

1. Fork the repository
2. Create a feature branch
3. Test with the GMU server: python test_gmu_connection.py
4. Test the interactive client: python tests/test_gmu.py
5. Submit a pull request

License

This project follows the same license as the GitHub MCP Server Multi-User.