python-github-plus-mcp

An MCP server that lets any MCP client work with GitHub (github.com and GitHub Enterprise Server): read repositories, branches, tags, pull requests, files and workflow runs, then optionally create branches, tags and pull requests, comment, assign, approve, trigger workflows, merge and delete.

It is a thin layer over python-github-plus, which does the GitHub work (defaults, validation, paging, error handling). This package only defines the tools and shapes their results for a model.

Requirements

• uv (it provides uvx, and installs Python 3.12+ if needed)

• git, to install straight from GitHub

• A GitHub fine-grained personal access token

curl -LsSf https://astral.sh/uv/install.sh | sh   # once, if uv is not installed

Related MCP server: GitHub MCP Server

Quick start

Claude Desktop

Add the server to claude_desktop_config.json, then restart the app:

{
  "mcpServers": {
    "github-plus": {
      "command": "/Users/you/.local/bin/uvx",
      "args": [
        "--from", "git+https://github.com/aviz92/python-github-plus-mcp@main",
        "python-github-plus-mcp"
      ],
      "env": {
        "GITHUB_ACCESS_TOKEN": "github_pat_..."
      }
    }
  }
}

• Use the full path to uvx (which uvx prints it). Claude Desktop does not load your shell's PATH.

• With @main, every restart of the app picks up the latest commit on main. To stay on one version, pin a tag instead, e.g. @v0.1.0.

• The token lives only in this local file. Never commit it.

• If you also run GitHub's official MCP server, give this one a different name (here github-plus).

Claude Code

claude mcp add github-plus \
  -e GITHUB_ACCESS_TOKEN=github_pat_... \
  -e GITHUB_MCP_DEFAULT_REPO=your-user/your-repo \
  -- uvx --from git+https://github.com/aviz92/python-github-plus-mcp@main python-github-plus-mcp

Token permissions

Give the token access only to the repositories the model should see, with these repository permissions:

A 403 from GitHub comes back as a tool error naming the permission the token is missing.

Configuration

All settings are environment variables (or a .env file in the working directory; see env.template). The credentials use the same names as python-github-plus, so one .env serves both.

Tools

Every tool takes repo (owner/name), falling back to GITHUB_MCP_DEFAULT_REPO. All repositories share one connection. List tools take limit and return truncated: true when more exist.

Enabling writes

Add to the server's env:

"GITHUB_MCP_READ_ONLY": "false"

Merging and deleting have their own switch because they cannot be undone:

"GITHUB_MCP_ENABLE_DESTRUCTIVE": "true"

Access and safety

• The server can do whatever the token can do. Limit it with a fine-grained token that covers only the repositories and permissions you want; GitHub enforces it on every request.

• Read-only by default, and merge/delete need a second, explicit switch.

• Not exposed on purpose: repository settings, branch protection and collaborator management, and waiting on a workflow run (a tool that blocks for minutes; the model polls github_get_workflow_run instead).

• File writes are not exposed: commit through branches and pull requests.

Docker and the HTTP transport (experimental)

docker build -t python-github-plus-mcp .
docker run -i --rm -e GITHUB_ACCESS_TOKEN -e GITHUB_MCP_DEFAULT_REPO python-github-plus-mcp

The image runs over stdio by default. GITHUB_MCP_TRANSPORT=streamable-http serves on GITHUB_MCP_HOST:GITHUB_MCP_PORT instead; in Docker, set GITHUB_MCP_HOST=0.0.0.0 and publish the port.

The HTTP transport has no authentication. Anyone who can reach the port acts with the configured token. Bind to loopback, or put an authenticating reverse proxy in front.

Development

git clone https://github.com/aviz92/python-github-plus-mcp
cd python-github-plus-mcp
uv sync --group dev
uv run pytest                 # mocked tests only
uv run pre-commit run --all-files

To run a client against your working copy, point it at the checkout:

"command": "/Users/you/.local/bin/uv",
"args": ["--directory", "/path/to/python-github-plus-mcp", "run", "python-github-plus-mcp"]

Integration tests

uv run pytest -m integration calls the tools through the server against the real GitHub API, with GITHUB_ACCESS_TOKEN from the environment or .env, and needs a sandbox repository:

License

MIT