gh-pr-mcp

A minimal MCP (Model Context Protocol) server exposing a focused set of GitHub PR and review helpers that the gh CLI doesn't cover well: structured PR review threads, GraphQL thread resolve/unresolve, inline-comment review submission, and per-comment edit/delete via the REST API.

Published to PyPI as gh-pr-mcp. The console script and MCP server are both named gh-pr-mcp.

Philosophy

git and gh are already great at what they do. Wrapping them tool-by-tool just bloats the agent's tool list and gets in the way. The tools that earn a spot here are the ones that:

1. Reduce token spend by composing verbose gh JSON output into a tight summary (e.g. pr_view, pr_list, run_view, run_job_view, pr_checks), or
2. Use the GitHub API directly for operations the gh CLI can't do in a single call (review-thread resolve/unresolve via GraphQL, replying to a specific review comment, editing/deleting review comments, posting a review with inline comments at specific lines).

Everything else — git status, git diff, gh pr create, gh issue list, etc. — is faster, simpler, and more flexible to call via the shell directly.

Tools

Recommended permission setup: allow everything in this server, and (separately) deny Bash(gh api …) so the model is funnelled through these helpers rather than rolling its own API calls.

GitHub Enterprise

Every tool picks the API host from the checkout's git remotes (gh's own remote order: upstream, github, origin), so enterprise repos work with no configuration as long as gh auth login --hostname <host> has been done. GH_HOST overrides the detection. The repo argument also accepts the three-part host/owner/name form when you need to target a different host than the checkout you're standing in.

Development

uv sync
uv run pytest          # tests
uv run pyrefly check   # type check
uv run gh-pr-mcp       # run the server over stdio

MCP configuration

Project-scoped (worktree under active development)

.mcp.json in your project root points at the worktree:

{
  "mcpServers": {
    "gh-pr-mcp-dev": {
      "command": "uvx",
      "args": ["--from", "/path/to/gh-pr-mcp-dev", "gh-pr-mcp"]
    }
  }
}

Global config (stable)

From PyPI:

{
  "mcpServers": {
    "gh-pr-mcp": {
      "command": "uvx",
      "args": ["gh-pr-mcp"]
    }
  }
}

Or straight from the repo without PyPI:

{
  "mcpServers": {
    "gh-pr-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/gordon-to/gh-pr-mcp", "gh-pr-mcp"]
    }
  }
}

gh must be installed and authenticated (gh auth login) — the tools shell out to it.

Architecture

src/gh_mcp/
├── server.py        # FastMCP app + tool registration
├── app.py           # mcp + @tool decorator
├── run.py           # subprocess helpers + input validation
└── tools/gh/
    ├── _api.py                # gh api GET/POST/PATCH/DELETE + GraphQL helpers
    ├── pr_view.py             # pr_view, pr_checks, pr_files, pr_review_threads
    ├── pr_list.py             # pr_list
    ├── pr_review.py           # pr_add_review, pr_reply_comment
    ├── pr_resolve_thread.py   # pr_resolve_thread, pr_unresolve_thread
    ├── pr_edit_comment.py
    ├── pr_delete_comment.py
    └── run_view.py            # run_view, run_job_view

License

AGPL-3.0-only. If you run a modified version as a network service, the AGPL requires you to offer that modified source to its users.