🐙 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

📦 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:

OS	Config path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/claude/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)

Tool	Description
auth_status	Check GitHub CLI authentication status
whoami	Get currently authenticated username
switch_account	Switch between GitHub accounts

Repos (5)

Tool	Description
create_repo	Create a new GitHub repository
list_repos	List repositories for a user/org
repo_view	View repository details
clone_repo	Clone a repository locally
delete_repo	Delete a repository (requires confirm=True)

Git (4)

Tool	Description
git_status	Get status of a local repository
git_add_commit_push	Add, commit, and push in one command
git_init_and_push	Initialize local dir, create GitHub repo, and push
git_pull	Pull latest changes from remote

Branches (4)

Tool	Description
create_branch	Create a new branch
list_branches	List branches in a repository
switch_branch	Switch to a different branch
delete_branch	Delete a branch

Forks (2)

Tool	Description
fork_repo	Fork a repository
sync_fork	Sync a fork with its upstream repository

Issues (3)

Tool	Description
create_issue	Create a new issue
list_issues	List repository issues
comment_on_issue	Add a comment to an issue

Pull Requests (6)

Tool	Description
create_pr	Create a pull request
list_prs	List pull requests
comment_on_pr	Add a comment to a PR
merge_pr	Merge a pull request
review_pr	Submit a review on a PR
pr_diff	View the diff of a pull request

Collaborators (2)

Tool	Description
list_collaborators	List collaborators on a repository
add_collaborator	Add a collaborator to a repository

File Operations (2)

Tool	Description
get_file_contents	Get the contents of a file from a repository
create_or_update_file	Create or update a file in a repository

Gists (1)

Tool	Description
create_gist	Create a GitHub gist

Workflows (4)

Tool	Description
list_workflows	List GitHub Actions workflows for a repo
run_workflow	Trigger a workflow dispatch event
list_workflow_runs	List recent workflow runs
view_workflow_run	View details of a specific workflow run

Search (1)

Tool	Description
search_repos	Search GitHub repositories

Releases (2)

Tool	Description
create_release	Create a new GitHub release
list_releases	List releases for a repository

🔒 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

Variable	Description	Default
WORK_DIR	Base directory for git operations (path sandbox root)	~/projects
READ_ONLY	Block all write operations when true	false
LOG_FILE	Path to the audit log file	mcp_audit.log
MCP_TRANSPORT	Transport mode: stdio or sse	stdio
MCP_PORT	Port for SSE server	8080
MCP_SERVER_URL	Public URL for OAuth issuer (ngrok URL)	http://localhost:8080

🏗️ 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.