gpt-github-max-mcp

An MCP (Model Context Protocol) server that gives ChatGPT — or any MCP client — maximum practical control over GitHub through the official GitHub REST and GraphQL APIs.

It exposes 22 tools covering repository browsing, file reads/writes, branches, commits (including multi-file atomic commits via the Git Data API), issues, pull requests, releases, Actions workflow/repository dispatch, Actions variables & secrets, and raw REST/GraphQL escape hatches.

⚠️ Warning: this server is as powerful as your token

This server has no independent safety layer. It does not add approval gates, branch protection rules, dry-run modes, or any restriction beyond what GitHub itself enforces. Every tool call is made directly against the GitHub API using GITHUB_TOKEN:

• If your token can push to main, merge PRs, delete files, dispatch workflows, or read/write secrets — so can this server, without asking for confirmation first.

• If GitHub denies a request (permissions, rate limits, branch protection, required reviews, etc.), that denial is returned to the caller as a clear error. GitHub — not this server — is the source of truth for what is and isn't allowed.

• Scope GITHUB_TOKEN deliberately (see Suggested token permissions below) and treat it like any other credential with production access.

If you want guardrails (required approvals, protected branches, no direct pushes to main, etc.), configure them on the GitHub side — via branch protection rules, required reviews, or a token scoped to only what you want to allow. Do not expect this server to add them for you.

Related MCP server: mcp-github

Requirements

• Python 3.11+

• A GitHub personal access token (fine-grained or classic)

Installation

git clone <this-repo>
cd gpt-github-max-mcp
python3 -m venv .venv && source .venv/bin/activate   # optional but recommended
pip install -e .

This installs the gpt-github-max-mcp console command.

Configuration (.env)

Copy the example file and fill in your token:

cp .env.example .env

GITHUB_TOKEN=github_pat_xxxxxxxxxxxxxxxxx
GITHUB_API_BASE=https://api.github.com
GITHUB_GRAPHQL_URL=https://api.github.com/graphql

MCP_HOST=127.0.0.1
MCP_PORT=8000

# Host/Origin allow-lists for the HTTP DNS-rebinding guard. "*" allows any
# Host/Origin header - normally required when exposing through a tunnel.
MCP_ALLOWED_HOSTS=*
MCP_ALLOWED_ORIGINS=*

• GITHUB_API_BASE / GITHUB_GRAPHQL_URL only need to change for GitHub Enterprise Server.

• MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS control FastMCP's built-in HTTP Host/Origin header guard (a basic network-layer protection, not a GitHub permission check). Leave as * for tunnel use, or restrict to your tunnel's hostname for tighter local hygiene.

Running locally

gpt-github-max-mcp

This starts an HTTP MCP server at:

http://127.0.0.1:8000/mcp

You can point any MCP-compatible client at that URL directly for local use (e.g. Claude Desktop, Claude Code, local test scripts).

Exposing it to ChatGPT

ChatGPT connects to MCP servers over HTTPS, so you need to put an HTTPS endpoint in front of your local server — via Cloudflare Tunnel, ngrok, or a VPS behind a real reverse proxy. See docs/CONNECT_CHATGPT.md for the full walkthrough, including adding the connector in ChatGPT and troubleshooting.

In all cases, restrict MCP_ALLOWED_HOSTS/MCP_ALLOWED_ORIGINS to the public hostname you're using once you've confirmed it works, rather than leaving them at * indefinitely on a long-running public endpoint.

Suggested GitHub fine-grained token permissions

Grant only what you intend to use. For full functionality across every tool in this server:

Fine-grained tokens can also be scoped to specific repositories/orgs — prefer that over an all-repository token when possible. For a full per-tool permission mapping, classic-scope equivalents, and what each GitHub error status means, see docs/TOKEN_PERMISSIONS.md.

Optional extras (both off by default)

These are operator conveniences, not safety features — neither changes what GitHub itself allows the token to do.

Audit log

Set AUDIT_LOG=true (and optionally AUDIT_LOG_PATH=/path/to/file, else it logs to stdout) to record every tool call — name, redacted arguments, and outcome — for local visibility into what the token was used for. Secret-bearing fields (e.g. secret_value) are always redacted; long string values are truncated.

Tool allowlist

Set MCP_TOOL_ALLOWLIST to a comma-separated list of tool names (e.g. whoami,list_repositories,read_file) to expose only that subset of tools to MCP clients. Leave unset to expose all 22 tools (the default).

Testing

pip install -e ".[dev]"
pytest

The test suite mocks all GitHub HTTP calls (via httpx.MockTransport) — no network access or real token required. For an end-to-end check against a live server (starts gpt-github-max-mcp, connects a real MCP client, verifies the tool list, and calls whoami):

python scripts/smoke_test.py

Example prompt for ChatGPT

Use github-max MCP. Run whoami, list my repositories, then for OWNER/REPO create branch ai/readme-mvp from main, write a professional README.md, commit it, and open a pull request. Do not merge.

Tool documentation

See TOOLS.md for the full list of tools, their parameters, the GitHub API endpoint each one calls, and the permission each requires.

Further reading

• docs/CONNECT_CHATGPT.md — exposing the server over HTTPS and wiring it up in ChatGPT

• docs/TOKEN_PERMISSIONS.md — per-tool permission mapping and error-status cheat sheet

• CHANGELOG.md — release history

Project structure

gpt-github-max-mcp/
├── README.md
├── TOOLS.md
├── CHANGELOG.md
├── .env.example
├── .gitignore
├── requirements.txt
├── pyproject.toml
├── docs/
│   ├── CONNECT_CHATGPT.md
│   └── TOKEN_PERMISSIONS.md
├── scripts/
│   └── smoke_test.py       # end-to-end check against a live server
├── tests/                  # pytest suite (httpx.MockTransport, no network)
├── .github/workflows/
│   └── ci.yml
└── src/
    └── gpt_github_max_mcp/
        ├── __init__.py
        ├── server.py          # FastMCP app + all 22 tool definitions
        ├── github_client.py   # httpx-based GitHub REST/GraphQL client
        └── schemas.py         # shared Pydantic input models