🐙 GitHub MCP Server

A Model Context Protocol (MCP) server that wraps the GitHub CLI (gh) to provide 39 tools across 12 categories — manage repos, branches, issues, PRs, workflows, collaborators, and more, directly from Claude Desktop or Claude Code.

🚀 Features

• Repository Management — Create, clone, list, view, and delete repos

• Git Operations — Add, commit, push, pull, init + push in one command

• Branch Management — Create, list, switch, and delete branches

• Forking — Fork repos and sync forks with upstream

• Issues — Create, list, and comment on issues

• Pull Requests — Create, list, comment, merge, review, and diff PRs

• Collaborators — List and add collaborators to repos

• File Operations — Read and create/update files via the GitHub API

• Workflows — List, trigger, and inspect GitHub Actions workflow runs

• Releases — Create and list releases

• Gists — Create gists from content

• Search — Search repositories across GitHub

• Security — Path sandboxing, input validation, read-only mode, audit logging

• Remote Access — SSE transport with OAuth 2.0 authentication via ngrok tunnel

Related MCP server: Git MCP

📦 Prerequisites

1. Install GitHub CLI

# macOS
brew install gh

# Ubuntu/Debian
sudo apt install gh

# Windows
winget install GitHub.cli

2. Authenticate

gh auth login
gh auth status   # Verify you're logged in

3. Python 3.10+

python --version  # Must be 3.10 or higher

🔧 Installation

# Clone the repository
git clone https://github.com/prateekaryann/github-mcp.git
cd github-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

🔌 Usage — Local (stdio)

This is the simplest setup. Claude Desktop or Claude Code launches the server as a subprocess.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "github": {
      "command": "python",
      "args": ["/path/to/github-mcp/server.py"],
      "cwd": "/path/to/github-mcp"
    }
  }
}

Restart Claude Desktop after adding the configuration.

Claude Code

claude mcp add github -- python /path/to/github-mcp/server.py

🌐 Usage — Remote (SSE + OAuth)

For remote access, the server runs an SSE endpoint with OAuth 2.0 authentication, exposed via an ngrok tunnel.

Step 1: Start an ngrok tunnel

ngrok http 8080
# Note the HTTPS forwarding URL, e.g. https://abc123.ngrok-free.app

Or use the included helper scripts:

# Linux/macOS
./tunnel.sh

# Windows (PowerShell)
.\tunnel.ps1

Step 2: Start the server in SSE mode

export MCP_TRANSPORT=sse
export MCP_PORT=8080
export MCP_SERVER_URL=https://abc123.ngrok-free.app  # Your ngrok URL
python server.py

Step 3: Connect from Claude Desktop

{
  "mcpServers": {
    "github-remote": {
      "url": "https://abc123.ngrok-free.app/sse"
    }
  }
}

The OAuth flow will prompt you to authorize when you first connect.

🛠️ Tools Reference

Auth (3)

Repos (5)

Git (4)

Branches (4)

Forks (2)

Issues (3)

Pull Requests (6)

Collaborators (2)

File Operations (2)

Gists (1)

Workflows (4)

Search (1)

Releases (2)

🔒 Security

Path Sandboxing

All local file operations are restricted to the WORK_DIR directory (default: ~/projects). Any path outside this directory is rejected, preventing unauthorized filesystem access.

Input Validation

Repository names, usernames, branch names, and file paths are validated against strict regex patterns to prevent injection attacks.

Read-Only Mode

Set READ_ONLY=true to restrict the server to safe, non-destructive operations only (list, view, search). All write operations will be blocked.

Audit Logging

Every tool invocation is logged with parameters to mcp_audit.log (configurable via LOG_FILE), providing a full audit trail of all operations.

OAuth 2.0 (Remote Mode)

When running in SSE mode, the server requires OAuth 2.0 authentication with configurable scopes (read, write). Client registration and token revocation are supported.

Dangerous Operation Confirmation

Destructive operations like delete_repo require an explicit confirm=True parameter to prevent accidental data loss.

⚙️ Configuration

🏗️ Architecture

github-mcp/
├── server.py           # Main MCP server — all 39 tools
├── oauth_provider.py   # In-memory OAuth 2.0 provider (SSE mode)
├── requirements.txt    # mcp[cli], uvicorn, starlette
├── tunnel.sh           # ngrok tunnel helper (Linux/macOS)
├── tunnel.ps1          # ngrok tunnel helper (Windows)
├── README.md
├── LICENSE
└── .claude/
    └── CLAUDE.md       # Claude Code project instructions

📝 License

MIT License — See LICENSE for details.

👤 Author

Prateek Aryan — @prateekaryann

Built for seamless GitHub integration with Claude.