GitHub MCP Server

A production-ready Model Context Protocol (MCP) server that exposes GitHub operations as AI-callable tools. Compatible with Claude Desktop, Cursor, VS Code agents, ChatGPT MCP clients, and any other MCP-compliant AI assistant.

Features

Related MCP server: GitHub MCP Tools

Tech Stack

• Python 3.11+ with FastMCP for MCP tool registration

• GitHub REST API v3 for all GitHub operations

• OAuth 2.0 (GitHub OAuth Apps) for user authentication

• FastAPI for the OAuth callback HTTP server

• SQLAlchemy + SQLite (or PostgreSQL) for token & audit storage

• Pydantic v2 for schema validation

• Docker + docker-compose for containerised deployment

Project Structure

github-mcp-server/
├── app/
│   ├── main.py        # FastAPI app + MCP entry point
│   ├── tools.py       # MCP tool definitions (@mcp.tool)
│   ├── auth.py        # OAuth 2.0 flow + token resolution
│   ├── github.py      # GitHub REST API v3 client
│   ├── database.py    # SQLAlchemy models + helpers
│   ├── schemas.py     # Pydantic request/response models
│   ├── config.py      # Settings via pydantic-settings
│   └── utils.py       # Shared helpers
├── tests/
│   ├── test_tools.py  # MCP tool unit tests
│   ├── test_auth.py   # Auth / token tests
│   └── test_github.py # GitHub API client tests
├── .env               # Environment variables (copy from this file)
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
└── README.md

Quick Start

1. Clone & install

git clone https://github.com/yourname/github-mcp-server
cd github-mcp-server
pip install -r requirements.txt

2. Configure environment

cp .env .env.local   # edit with your values

Minimum required variables:

GITHUB_TOKEN=ghp_your_personal_access_token   # easiest for dev
# OR set up a GitHub OAuth App and fill in:
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

Create a GitHub OAuth App at: GitHub → Settings → Developer settings → OAuth Apps → New OAuth App

• Homepage URL: http://localhost:8000

• Callback URL: http://localhost:8000/auth/callback

3. Run

HTTP mode (OAuth server + health endpoints):

python -m app.main
# Open http://localhost:8000/docs for the Swagger UI

MCP stdio mode (for Claude Desktop / Cursor / VS Code):

python -m app.main stdio

4. Run tests

pytest tests/ -v

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "github": {
      "command": "python",
      "args": ["-m", "app.main", "stdio"],
      "cwd": "/path/to/github-mcp-server",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Then ask Claude:

• "Create a repository named portfolio-website"

• "Create a bug issue in portfolio-website: login button broken"

• "Show latest commits from portfolio-website"

• "Create a pull request from feature/login to main"

• "List open issues in my repository"

• "Search repositories related to LangGraph"

Docker

# Build and start
docker-compose up --build

# Run with Postgres instead (uncomment db service in docker-compose.yml):
# DATABASE_URL=postgresql://mcp:secret@db:5432/github_mcp

API Endpoints (HTTP mode)

Authentication Modes

The server resolves tokens in this order:

1. DB-stored OAuth token for the given login

2. GITHUB_TOKEN env var (PAT)

Database

SQLite by default (zero config). Switch to Postgres by changing DATABASE_URL:

DATABASE_URL=postgresql://user:password@localhost:5432/github_mcp

Tables created automatically on startup:

• token_store — OAuth tokens keyed by GitHub login

• audit_log — Lightweight tool call history