GitHub MCP Connector

A Model Context Protocol (MCP) server that connects Claude to GitHub. It exposes 120+ GitHub REST API operations as MCP tools, so Claude (Desktop, Code, or any MCP client) can search and read repositories, files, and commit history; triage and comment on issues; review, open, and merge pull requests; drive CI (read logs, re-run, dispatch); inspect security alerts; and—optionally—make changes (open/merge PRs, submit reviews, manage labels/assignees, commit files, cut releases). Every write is gated by a single read-only switch.

It's a small, dependency-light Python package (mcp + httpx) that you point at a GitHub token. It supports both stdio (the default for Claude Desktop/Code) and streamable HTTP transports, and works against github.com or GitHub Enterprise Server.

Features

• 🔍 Search & discover repositories, issues, PRs, commits, code, and users — plus find reusable repos (across everything your token can see, license/activity-aware) for what you're building
• 📦 Repositories — metadata, branches, tags, file contents, directory listings, languages, topics, collaborators, your repo list; create/fork repos and update settings
• 🧾 Commits — history, single-commit detail, diffs between refs, and set commit statuses
• 🐛 Issues — list, read, create, comment, read comments, edit/close, label, assign, lock/unlock, milestones
• 🔀 Pull requests — list, read, diffs/files/commits, comments, open, update, merge, review, and request reviewers
• ⚙️ Actions & releases — list workflows/runs/jobs, read failed-job logs, re-run/dispatch/cancel/schedule workflows, commit statuses & check runs, full release lifecycle (create/edit/delete, changelog notes, assets) & tags
• 🔐 Security — secret-scanning, code-scanning, and Dependabot alerts (list each or all-in-one, fetch one by number, dismiss/resolve, and open tracking issues per alert)
• 🔔 Notifications — list and mark read across all your repos
• ✍️ Repo writes — create/fork repos, create branches, commit/delete files, manage labels (create/edit/delete) & assignees, request PR reviewers, create/edit gists (gated by read-only mode)
• 📄 Pagination — every list tool takes page, so you can read past the first 100 items
• ♻️ Resilient — honours Retry-After and rate-limit headers; retries transient failures (never replaying a write)
• 🎯 Scopable — GITHUB_MCP_TOOLS loads only the tool groups you need
• 🔒 Read-only mode — flip one env var to disable every write tool
• 🏢 Enterprise-friendly — set GITHUB_API_URL for GitHub Enterprise Server

Tools

Tools marked Write are disabled when GITHUB_MCP_READ_ONLY is set.

Requirements

• Python 3.10+
• A GitHub personal access token. The connector applies no repository restrictions of its own — it can reach exactly the repositories your token can, so token scope is what controls access:
  • All your repositories (recommended for general use): create a classic PAT with the repo scope, or a fine-grained PAT whose "Repository access" is set to All repositories. This lets the connector see every repo your account can access (public and private).
  • Only specific repositories: use a fine-grained PAT and select just those repos under "Repository access".
  • Permissions: read access is enough for the read tools. The write tools need scopes matching what they touch — for a classic PAT the repo scope covers most (issues, PRs, reviews, labels, assignees, branches, files, releases, statuses), workflow is required for trigger_workflow / rerun_workflow_run, and gist for create_gist. Fine-grained tokens need the corresponding per-resource "Read and write" permissions (Contents, Issues, Pull requests, Actions, etc.), and security-alert tools require the relevant code-scanning/Dependabot/secret-scanning alert read permissions.

Install from PyPI (recommended)

The connector is published to PyPI as github-mcp-connector, so you can install or run it by name — no clone, no git, no build step. This is the most reliable option on Windows, where launching from a git URL requires Git on the spawned process's PATH.

uvx github-mcp-connector            # run on demand with uv (nothing to install)
pipx run github-mcp-connector       # same, with pipx
pip install github-mcp-connector    # or install it permanently

Wire it into Claude by pointing the command at the published package:

Claude Code:

claude mcp add-json github '{
  "command": "uvx",
  "args": ["github-mcp-connector"],
  "env": { "GITHUB_TOKEN": "github_pat_your_token_here" }
}'

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "github": {
      "command": "uvx",
      "args": ["github-mcp-connector"],
      "env": { "GITHUB_TOKEN": "github_pat_your_token_here" }
    }
  }
}

On Windows, use the full path to uvx.exe (run where.exe uvx to find it), e.g. C:\\Users\\you\\.local\\bin\\uvx.exe.

Quick start (no clone, no venv)

If the package isn't published yet (or you want to track an unreleased commit), uvx can also fetch, build, and run the connector straight from GitHub. This path requires Git to be available to the process that launches it.

Claude Code — one command:

claude mcp add-json github '{
  "command": "uvx",
  "args": ["--from", "git+https://github.com/winnerlose2026/Github-mcp.git", "github-mcp"],
  "env": { "GITHUB_TOKEN": "github_pat_your_token_here" }
}'

Add --scope user to make it available in every project. Verify with claude mcp list (should show github connected).

Claude Code — project-scoped, shareable: this repo ships a .mcp.json that reads GITHUB_TOKEN from your environment. Drop the same file in any project (or copy it from here), export your token, and Claude Code auto-detects it:

export GITHUB_TOKEN=github_pat_your_token_here
claude   # prompts once to approve the project MCP server

Claude Desktop: point the command at uvx so there's no interpreter path to manage:

{
  "mcpServers": {
    "github": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/winnerlose2026/Github-mcp.git", "github-mcp"],
      "env": { "GITHUB_TOKEN": "github_pat_your_token_here" }
    }
  }
}

Prefer pipx? pipx run --spec git+https://github.com/winnerlose2026/Github-mcp.git github-mcp works the same way; use that as the command/args instead.

Installation (from source)

For development, or if you don't use uv/pipx:

git clone https://github.com/winnerlose2026/Github-mcp.git
cd Github-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .

Or, without installing, from the repo root:

pip install -r requirements.txt
python -m github_mcp

Configuration

All configuration comes from environment variables (see .env.example):

Connecting to Claude (from-source install)

If you installed from source (above) instead of using uvx/pipx, configure the client to run the package directly.

Claude Desktop

Add the server to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "github": {
      "command": "python",
      "args": ["-m", "github_mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Use the absolute path to the Python interpreter from the virtualenv where you installed the package (e.g. /path/to/Github-mcp/.venv/bin/python), or the github-mcp console script directly. Restart Claude Desktop after editing.

Claude Code

claude mcp add github \
  --env GITHUB_TOKEN=ghp_your_token_here \
  -- python -m github_mcp

Streamable HTTP

To run as a standalone HTTP server instead of stdio:

GITHUB_TOKEN=ghp_your_token_here python -m github_mcp --http

Example prompts

Once connected, you can ask Claude things like:

• "What's the open PR backlog on owner/repo?"
• "Read README.md from the default branch of owner/repo and summarize it."
• "Show me the diff for PR #42 and summarize the risky parts."
• "Open an issue titled 'Flaky test in CI' with these reproduction steps…"

Development

pip install -e ".[dev]"
pytest

The test suite mocks the GitHub API with httpx.MockTransport, so it runs fully offline and makes no network calls.

Releasing (maintainers)

Publishing is automated via GitHub Actions (.github/workflows/publish.yml) using PyPI Trusted Publishing (OIDC) — no API tokens are stored anywhere.

One-time PyPI setup (before the first release):

1. Sign in at pypi.org and go to Your projects → Publishing (or Account → Publishing for a project that doesn't exist yet).
2. Add a pending publisher with:
   • PyPI Project Name: github-mcp-connector
   • Owner: winnerlose2026
   • Repository: Github-mcp
   • Workflow name: publish.yml
   • Environment name: pypi
3. (Recommended) In the GitHub repo, create an Environment named pypi (Settings → Environments) so the publish job is gated.

Cutting a release:

1. Bump version in pyproject.toml, commit, and merge to main.
2. Tag and publish a GitHub Release (e.g. v0.1.0). Publishing the release triggers the workflow, which builds the sdist + wheel, runs twine check, and uploads to PyPI.
3. Confirm it's live: uvx github-mcp-connector@latest --help.

Until the first release is published, install via the git-based quick start instead.

Security notes

• The connector only has the access your token grants. A broad token (repo scope / all repositories) gives Claude reach across every repo your account can touch — convenient, but treat the token like the credential it is. Prefer a fine-grained, repo-limited token if you only need a few repositories.
• Run with GITHUB_MCP_READ_ONLY=true when you only need read access; this is enforced server-side, before any write request is sent to GitHub. This pairs well with a broad-access token: full visibility, no write risk.
• Never commit your token. .env is git-ignored; .env.example is the template to copy.

License

MIT