# github-pr-review-mcp

A local MCP server for reviewing GitHub pull requests: it reads PR diffs, reads
your coding standards, and posts inline review comments / a full review back
to the PR — all driven by whatever MCP client you connect it to (e.g. Claude
Desktop or Claude Code).

Scope is intentionally narrow: this server can only read PR/repo data and
post PR review comments/reviews. It cannot edit files, push commits, merge,
delete, or manage anything else in your GitHub account.

## Tools

| Tool | Read/Write | Description |
|---|---|---|
| `github_whoami` | read | Verify the token works, show the authenticated user |
| `github_list_pull_requests` | read | List open/closed/all PRs on a repo |
| `github_get_pull_request` | read | Full PR metadata, including `head_sha` |
| `github_get_pull_request_diff` | read | Full unified diff for a PR |
| `github_get_pull_request_files` | read | Per-file patches + add/delete counts |
| `github_get_review_standards` | read | Your local `STANDARDS.md` and/or a standards file from inside the target repo |
| `github_list_review_comments` | read | Existing inline comments already on the PR |
| `github_post_review_comment` | write | Post one standalone inline comment |
| `github_submit_pr_review` | write | Submit a full review: summary + verdict (COMMENT/APPROVE/REQUEST_CHANGES) + inline comments |

## 1. Create a GitHub token

1. GitHub → Settings → Developer settings → **Fine-grained personal access tokens** → Generate new token.
2. Resource owner: your account (or the org that owns the repos you'll review).
3. Repository access: select the specific repos you want this server to touch.
4. Permissions → **Pull requests: Read and write**. (Also grant **Contents: Read-only** if you want `github_get_review_standards` to fetch a standards file from inside the repo.)
5. Generate and copy the token (starts with `github_pat_` or `ghp_`).

## 2. Install dependencies

```bash
cd github-pr-review-mcp
python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

## 3. Configure

Edit `STANDARDS.md` in this folder to reflect the standards you actually want
enforced (it ships with a generic starter template — trim/expand it).

Set your token as an environment variable, or wire it into your MCP client
config directly (see step 4) — either works, you don't need both.

```bash
export GITHUB_TOKEN=github_pat_xxxxxxxxxxxx
```

## 4. Register with your MCP client

**Claude Desktop** — edit `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "github-pr-review": {
      "command": "/absolute/path/to/github-pr-review-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/github-pr-review-mcp/server.py"],
      "env": {
        "GITHUB_TOKEN": "github_pat_xxxxxxxxxxxx"
      }
    }
  }
}
```

**Claude Code** — from the project directory:

```bash
claude mcp add github-pr-review \
  --env GITHUB_TOKEN=github_pat_xxxxxxxxxxxx \
  -- /absolute/path/to/github-pr-review-mcp/.venv/bin/python /absolute/path/to/github-pr-review-mcp/server.py
```

Restart the client after editing config. Then ask it to run `github_whoami`
to confirm the connection works.

## 5. Typical review flow

Once connected, a prompt like this drives the whole workflow:

> Review PR #42 on ososerp-web against our standards and post comments.

Under the hood the client will typically:
1. `github_get_review_standards` (local + repo-side)
2. `github_get_pull_request` (get `head_sha`)
3. `github_get_pull_request_files` or `github_get_pull_request_diff`
4. `github_list_review_comments` (avoid duplicate feedback)
5. `github_submit_pr_review` with inline comments and a verdict

## Managing context/token usage on large PRs

Tool results stay in context for the rest of the session, so a couple of
knobs help keep big PRs from flooding it:

- `github_get_pull_request_files` truncates each file's patch to `max_patch_chars`
  (default 2500) and returns `patch_truncated: true` when it cut something off.
  Pass `include_patch=false` for a filenames-only overview first, then use
  `paths=["src/big_file.ts"]` to re-fetch just the file(s) you actually need
  to inspect closely (optionally with a higher `max_patch_chars`).
- `github_get_pull_request_diff` truncates to `max_chars` (default 8000). For
  anything beyond a small PR, prefer `github_get_pull_request_files` instead —
  it lets you review file-by-file rather than pulling the whole diff at once.
- List-heavy tools return compact (non-pretty-printed) JSON to shave a bit
  more off every call.

The general pattern for a large PR: call `github_get_pull_request_files` with
`include_patch=false` first to see what changed, then selectively pull full
patches only for the files that look like they need real scrutiny.

## 6. Automate it: review every PR automatically

Rather than typing a prompt each time, you can trigger a review the moment
a PR opens, using a GitHub Actions workflow that runs Claude headlessly.

**Note:** If your org is on a Claude Team/Enterprise plan, Anthropic also
offers a fully-managed **Code Review** feature (org admin enables it once,
no workflow file needed, tune it with a `REVIEW.md` in the repo). See
[code review docs](https://code.claude.com/docs/en/code-review). What
follows is the self-hosted alternative that reuses *this* server and your
`STANDARDS.md` directly, works on any plan, and gives you full control over
the tools/prompt.

This repo already includes the pieces:
- `.github/workflows/pr-review.yml` — triggers on PR opened/synchronize/reopened
- `mcp-config.json` — tells Claude Code how to launch this server in CI

**Setup:**

1. Copy this whole `github-pr-review-mcp/` folder (including `.github/workflows/pr-review.yml` and `mcp-config.json`) into the root of the repo you want auto-reviewed. (Or add it as a git submodule if you want it to stay in sync across repos.)
2. In that repo's GitHub settings → Secrets and variables → Actions, add `ANTHROPIC_API_KEY` (from [console.anthropic.com](https://console.anthropic.com)).
3. Push a test PR. Within a minute or two you should see review comments posted by the `github-actions[bot]` account.

**Caveats:**
- The workflow uses the default `secrets.GITHUB_TOKEN`, which only has write access for PRs within the same repo. PRs from forks run with a read-only token and no access to secrets by default (GitHub's security model) — reviewing external contributors' PRs automatically needs a `pull_request_target` workflow instead, which is more advanced and requires care not to check out/execute untrusted code.
- Each review run costs Claude API tokens (scales with PR size); consider limiting the trigger to `opened` only (drop `synchronize`) if you don't need re-review on every push.

## Notes on line numbers

GitHub's review-comment API expects `line` to be a line number that actually
appears in the diff hunk for that file (from `github_get_pull_request_files`'
`patch` field), not an arbitrary line in the full file. If a comment call
returns a 422 error, re-check the patch/hunk for that file first.

## Troubleshooting

- **401 error**: `GITHUB_TOKEN` missing, expired, or not picked up — confirm it's set in the exact process/config running the server.
- **403 error**: token lacks "Pull requests" permission on that repo, or the repo is private and the token/account can't see it.
- **404 error**: wrong owner/repo/PR number, or no access to a private repo.
- **422 on posting a comment**: the `line`/`path`/`side` combination doesn't correspond to a changed line in the diff.