gpt-github-max-mcp

<p align="center"> <img src="docs/assets/banner.svg" alt="GPT GitHub Max MCP — maximum practical GitHub control for ChatGPT and MCP clients" width="100%"> </p>

<p align="center"> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+"></a> <a href="https://github.com/alikhande70/gpt-github-max-mcp/actions/workflows/ci.yml"><img src="https://github.com/alikhande70/gpt-github-max-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-5A32FB.svg" alt="MCP compatible"></a> <a href="https://docs.github.com/en/rest"><img src="https://img.shields.io/badge/GitHub%20API-REST%20%2B%20GraphQL-181717.svg" alt="GitHub REST + GraphQL"></a> <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a> </p>

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.

How it works

<p align="center"> <img src="docs/assets/overview.svg" alt="Architecture overview: a ChatGPT or MCP client talks to the gpt-github-max-mcp FastMCP server over HTTP, scoped entirely by GITHUB_TOKEN, which maps 22 tools onto the GitHub REST and GraphQL API across repositories, branches, commits, pull requests, and Actions" width="100%"> </p>

A client speaks the MCP protocol to this server; the server is a thin, 1:1 bridge onto GitHub's own REST and GraphQL APIs, scoped entirely by whatever GITHUB_TOKEN it's given. Nothing in between adds its own notion of what's allowed — that's still GitHub's call.

Quick start

git clone <this-repo> && cd gpt-github-max-mcp
pip install -e .
cp .env.example .env   # then set GITHUB_TOKEN
gpt-github-max-mcp     # serves http://127.0.0.1:8000/mcp

Then put an HTTPS tunnel in front of it (e.g. cloudflared tunnel --url http://127.0.0.1:8000) and add the resulting .../mcp URL as a connector in ChatGPT. Full walkthrough, including troubleshooting: docs/CONNECT_CHATGPT.md.

The sections below cover each of these steps in detail.

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:

Permission	Access level
Contents	Read and write
Pull requests	Read and write
Issues	Read and write
Actions	Read and write
Workflows	Read and write
Secrets	Read and write
Variables	Read and write
Metadata	Read-only
Administration	Read and write (only if you need repo admin operations)
Deployments	Read and write (only if you need deployment operations)

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
├── LICENSE
├── .env.example
├── .gitignore
├── requirements.txt
├── pyproject.toml
├── docs/
│   ├── CONNECT_CHATGPT.md
│   ├── TOKEN_PERMISSIONS.md
│   └── assets/
│       ├── banner.svg
│       └── overview.svg
├── 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