GitHub MCP Server

A comprehensive Model Context Protocol (MCP) server for the GitHub API, built with Python and the official MCP SDK.

This server exposes 87 tools across 25 categories, enabling AI agents like Claude to interact with GitHub repositories, issues, pull requests, discussions, projects, and more.

Features

Requirements

• Python >= 3.10
• uv (recommended) or pip
• GitHub Personal Access Token

Installation

git clone https://github.com/software-engineer-mj/github-mcp.git
cd github-mcp
uv sync

Configuration

cp .env.example .env

Edit the .env file:

GITHUB_TOKEN=ghp_your_token_here

Token Permissions

Depending on which tools you use, your token needs these scopes:

Usage

stdio (default)

uv run python -m github_mcp

Docker

docker build -t github-mcp .

docker run -e GITHUB_TOKEN=ghp_your_token github-mcp

MCP Client Configuration

Claude Desktop

Add to claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "github": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/github-mcp", "python", "-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Claude Code

Add to .mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/github-mcp", "python", "-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Development

# Install with dev dependencies
uv sync --dev

# Run tests
uv run pytest tests/ -v

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

# Type check
uv run mypy src/

Tool Reference

Repositories

Issues

Pull Requests

Search

Actions

Releases

Tags

Git

Organizations

Branches

Branch Protection

Webhooks

Files

PR Reviews

Review Comments

Commit Statuses

Labels

Gists

Stars

Users

Notifications

Collaborators

Discussions

Projects (Classic)

Projects V2

Project Structure

src/github_mcp/
├── __init__.py              # FastMCP server instance
├── __main__.py              # Entry point with auto-discovery
├── client.py                # Async GitHub API HTTP client (httpx)
├── exceptions.py            # Custom exception hierarchy
├── validators.py            # Input validation (enum, clamping)
└── tools/
    ├── __init__.py
    ├── actions.py            # GitHub Actions workflows
    ├── branch_protection.py  # Branch protection rules
    ├── branches.py           # Branch management
    ├── collaborators.py      # Collaborator management
    ├── commit_statuses.py    # Commit statuses and check runs
    ├── discussions.py        # Discussions (GraphQL)
    ├── files.py              # File create/update/delete
    ├── gists.py              # Gist operations
    ├── git.py                # Git Data API (tree, push files)
    ├── issues.py             # Issue operations
    ├── labels.py             # Label management
    ├── notifications.py      # Notification management
    ├── organizations.py      # Organization operations
    ├── projects.py           # Classic project boards
    ├── projects_v2.py        # Projects V2 (GraphQL)
    ├── pull_requests.py      # Pull request operations
    ├── releases.py           # Release management
    ├── repositories.py       # Repository operations
    ├── review_comments.py    # PR review comments
    ├── reviews.py            # PR review operations
    ├── search.py             # GitHub search
    ├── stars.py              # Star/unstar repositories
    ├── tags.py               # Tag operations
    ├── users.py              # User profile operations
    └── webhooks.py           # Webhook management
tests/
├── conftest.py              # Shared fixtures (mock GitHub client)
├── test_client.py           # HTTP client, retry, cache, error tests
├── test_exceptions.py       # Exception hierarchy tests
├── test_server.py           # Tool registration tests
├── test_validators.py       # Validator tests
└── tools/
    ├── conftest.py
    └── test_<domain>.py      # Tests matching each tool module

License

MIT - see LICENSE for details.