🐙 GitHub MCP Server

MCP server for GitHub operations — 73 tools for repos, PRs, issues, actions, releases, search, and more.

A comprehensive Model Context Protocol (MCP) server that exposes the full GitHub REST API as AI-ready tools. Connect your AI assistant (Cursor, Claude Desktop, or any MCP client) to manage GitHub through natural language.

Author: Pawan Gunjkar (pawangunjkar@gmail.com)

📥 Install

Option 1: PyPI / uvx (Recommended)

No clone required — install and run directly:

uvx pawangunjkar-github-mcp

Cursor / Claude Desktop — add to .cursor/mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "github": {
      "command": "uvx",
      "args": ["pawangunjkar-github-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your-token-here",
        "GITHUB_PROTOCOL": "ssh"
      }
    }
  }
}

Option 2: Smithery

npx -y @smithery/cli install github-mcp --client cursor

Or browse smithery.ai and search for github-mcp.

Option 3: Clone from GitHub

git clone https://github.com/Pawangunjkar/github-mcp.git
cd github-mcp
uv sync
uv run server.py

See PUBLISHING.md for PyPI, Smithery, and directory submission steps.

✨ Features

• 🔌 73 tools across 12 categories — full GitHub API coverage
• 🔐 PAT authentication — Personal Access Token with Bearer auth
• 🔄 SSH + HTTPS — supports both clone/push protocols
• 📄 Auto-pagination — transparently handles paginated API responses
• ⚡ Rate limit aware — tracks and warns on low rate limits
• 💾 Credential caching — auto-connect from env vars or cached credentials
• 🏢 GitHub Enterprise — configurable API URL for GHE servers
• 🎯 Zero configuration — just set env vars and run

🚀 Quick Start

Prerequisites

• Python 3.10+
• uv package manager
• GitHub account with a Personal Access Token

1. Clone & Install

cd github-mcp
uv sync

2. Configure Credentials

Option A: Environment Variables (Recommended)

cp .env.example .env

# Set your GitHub PAT
GITHUB_TOKEN=ghp_your-personal-access-token
GITHUB_PROTOCOL=ssh    # or 'https'

Option B: Connect via chat

github_connect(token="ghp_xxxxxxxxxxxx", protocol="ssh")

3. Generate a Personal Access Token

1. Go to GitHub → Settings → Developer settings → Personal access tokens
2. Click "Generate new token" (classic)
3. Select scopes: repo, workflow, read:org, gist, notifications, delete_repo
4. Click Generate and copy the token

4. Run the Server

# For Cursor / Claude Desktop (stdio transport)
uv run server.py

# For testing with MCP Inspector
uv run mcp dev server.py

🛠️ Tool Reference (73 Tools)

Category 1: Connection & Authentication (4 tools)

Category 2: Repository Management (10 tools)

Category 3: Branch & Tag Management (8 tools)

Category 4: File & Content Operations (6 tools)

Category 5: Pull Requests (10 tools)

Category 6: Issues (8 tools)

Category 7: Actions & Workflows (7 tools)

Category 8: Releases (5 tools)

Category 9: Users & Organizations (5 tools)

Category 10: Search (4 tools)

Category 11: Gists (4 tools)

Category 12: Webhooks & Notifications (2 tools)

🔗 SSH vs HTTPS Support

The server supports both protocols. Set your preference via:

• Environment variable: GITHUB_PROTOCOL=ssh (or https)
• Connection parameter: github_connect(token="...", protocol="ssh")

Tools like github_create_repo, github_fork_repo, and github_get_clone_url return URLs in both formats.

⚙️ Configuration

Environment Variables

Cursor Integration

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "uvx",
      "args": ["pawangunjkar-github-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your-token-here",
        "GITHUB_PROTOCOL": "ssh"
      }
    }
  }
}

Alternative (from source):

{
  "mcpServers": {
    "github": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/github-mcp", "server.py"],
      "env": {
        "GITHUB_TOKEN": "ghp_your-token-here",
        "GITHUB_PROTOCOL": "ssh"
      }
    }
  }
}

Claude Desktop Integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "github": {
      "command": "uvx",
      "args": ["pawangunjkar-github-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your-token-here",
        "GITHUB_PROTOCOL": "ssh"
      }
    }
  }
}

💡 Example Usage

Repository Management

"List all my repos sorted by recent activity"
→ github_list_repos(sort="updated")

"Show me the details of the linux-ssh-mcp repo"
→ github_get_repo(owner="Pawangunjkar", repo="linux-ssh-mcp")

"Fork the fastapi repo to my account"
→ github_fork_repo(owner="tiangolo", repo="fastapi")

Pull Requests & Code Review

"Create a PR from feature-branch to main"
→ github_create_pr(owner="me", repo="my-app", title="Add login feature", head="feature-branch", base="main")

"Show me the files changed in PR #42"
→ github_list_pr_files(owner="me", repo="my-app", pr_number=42)

"Merge PR #42 with squash"
→ github_merge_pr(owner="me", repo="my-app", pr_number=42, merge_method="squash")

GitHub Actions

"Trigger the deploy workflow on main branch"
→ github_trigger_workflow(owner="me", repo="my-app", workflow_id="deploy.yml", ref="main")

"Show recent workflow runs"
→ github_list_workflow_runs(owner="me", repo="my-app")

"Cancel the running workflow"
→ github_cancel_workflow_run(owner="me", repo="my-app", run_id=12345)

Search

"Find popular Python MCP servers on GitHub"
→ github_search_repos(query="mcp server language:python stars:>10")

"Search for FastMCP usage in code"
→ github_search_code(query="FastMCP language:python")

📁 Project Structure

github-mcp/
├── server.py              # Main MCP server — 73 tool definitions
├── github_client.py       # GitHub REST API client (HTTP, auth, pagination)
├── credential_store.py    # Credential caching (env vars, memory, file)
├── pyproject.toml         # Project metadata & dependencies
├── .env.example           # Example environment variables
├── .gitignore             # Python gitignore
├── LICENSE                # MIT license
└── README.md              # This file

🔒 Security Notes

• PAT tokens are stored in ~/.github-mcp-cache/credentials.json with restrictive file permissions (600)
• Never commit .env files or tokens to version control
• Use fine-grained tokens when possible for minimum required access
• The server tracks rate limits and warns when running low

📄 License

MIT License — see LICENSE for details.