GitHub MCP Agent Server

MCP server giving AI agents controlled GitHub access with policy guard and audit trail.

Architecture

   ┌───────────────┐        MCP stdio         ┌───────────────────┐
   │   AI Agent    │ ◄──────────────────────► │ GitHub MCP Server │
   │ (Claude, Codex│      JSON-RPC 2.0        │                   │
   │   or any MCP  │                         ┌─┴───────────────┐   │
   │    client)    │                         │ Policy Guard    │   │
   └───────────────┘                         ├─────────────────┤   │
                                             │ Audit Log       │   │
                                             └─────────────────┘   │
           ┌──────────────────────────────────────────────┐      │
           │                 github_client.py               │      │
           │                    (httpx)                     │      │
           │                   GitHub API                   │      │
           └──────────────────────────────────────────────┘      │
           ┌──────────────────────────────────────────────┐      │
           │          Review Engine (ruff + regex)          │      │
           └──────────────────────────────────────────────┘      │
                                                                └───┘

Features & Tools

Security Model

• Repository Allowlist: Only repositories explicitly allowed by policy can be accessed.
• Branch Protection: PRs to protected branches are subject to branch protection rules before merging.
• Dry-Run Mode: Execute operations without side effects for safe testing and auditing.
• Audit Logging: All actions logged in JSONL format with precise timestamps to maintain traceability.
• Policy Configuration: Start from policy.example.json to configure repository allowlists and protected branches.

FAQ

Why not call the GitHub API directly?
Direct API calls lack centralized policy enforcement, audit logging, and uniform tooling support for AI agents. This MCP server adds a controlled, auditable layer for safer automation.

What MCP clients work with this?
Agents like Claude Code, OpenAI Codex, and any client supporting the MCP JSON-RPC 2.0 transport can connect to this server.

How is this different from the official GitHub MCP server?
This project's key differentiator is policy enforcement. Repository allowlists prevent agents from touching unauthorized repos, branch protection blocks accidental PRs to sensitive branches, dry-run mode supports safe validation, and write actions are audit-logged with timestamps.

Quick Start

Prerequisites

• Python 3.10+
• GitHub personal access token with repo scope

Install

pip install fastmcp httpx python-dotenv

Configure and Run

git clone https://github.com/FMorgan-111/github-mcp-server.git
cd github-mcp-server
cp .env.example .env && nano .env
python3 -m src.main

Connect with Claude Code

claude mcp add github-agent -- python3 /path/to/github-mcp-server/src/main.py

Development

pip install -e . --break-system-packages
python3 -m pytest tests/ -v
python3 -m src.main

106 tests, all passing.

Docker Deployment

docker build -t github-mcp-server .
docker run \
  -e GITHUB_TOKEN=ghp_your_token_here \
  -i github-mcp-server

The -e GITHUB_TOKEN=... flag passes the token into the container because the local .env file is not copied into the image.

License

MIT