# GitHub PR Control MCP

A focused, production-ready [Model Context Protocol](https://modelcontextprotocol.io/)
server for triaging and reviewing GitHub pull requests. It uses the GitHub REST
API directly—there is no `gh` CLI wrapper and no shell execution.

## What it does

The server exposes eight typed tools:

| Tool | Purpose | Default permission |
| --- | --- | --- |
| `list_prs` | List and paginate open, closed, or all PRs | Read |
| `get_pr` | Fetch PR metadata, branches, labels, merge state, and counts | Read |
| `get_pr_diff` | Fetch and page through a raw unified diff | Read |
| `list_pr_comments` | Read inline reviews and top-level conversation comments | Read |
| `post_review_comment` | Post an inline single- or multi-line diff comment | Write |
| `submit_review` | Approve, comment, or request changes | Write |
| `add_labels` | Add labels without replacing existing labels | Write |
| `request_changes` | Submit a dedicated change-request review | Write |

Large repositories and pull requests are first-class:

- `list_prs` and `list_pr_comments` fetch up to 20 GitHub API pages per call.
- `get_pr_diff` returns an `offset`, `next_offset`, and `total_lines`, so clients
  can process a huge diff in bounded chunks.
- Every response includes the last observed GitHub rate-limit budget.
- GitHub failures surface the remaining budget and reset time when GitHub
  provides them.

## Install

Requires Node.js 20 or newer.

```bash
npx github-pr-control-mcp
```

Or install it globally:

```bash
npm install --global github-pr-control-mcp
github-pr-control-mcp
```

## Authentication and permission model

Read-only mode is the default. Choose either a personal access token (PAT) or a
GitHub App installation.

### PAT: read-only

```bash
GITHUB_READ_TOKEN=github_pat_read_only npx github-pr-control-mcp
```

`GITHUB_TOKEN` is accepted as an alias for `GITHUB_READ_TOKEN`.

### PAT: separate read and write tokens

```bash
GITHUB_READ_TOKEN=github_pat_read_only \
GITHUB_WRITE_TOKEN=github_pat_write_scoped \
npx github-pr-control-mcp
```

The server will not run a write tool unless `GITHUB_WRITE_TOKEN` is present.
For a single-token setup, set `GITHUB_WRITE_ENABLED=true`; the configured read
token will then also handle writes.

Recommended fine-grained PAT permissions:

- Read tools: **Pull requests: Read**, **Contents: Read**, **Metadata: Read**
- Review tools: **Pull requests: Read and write**
- Label tool: **Issues: Read and write**

### GitHub App

```bash
GITHUB_APP_ID=123456 \
GITHUB_INSTALLATION_ID=9876543 \
GITHUB_APP_PRIVATE_KEY_PATH=/secure/path/app-private-key.pem \
npx github-pr-control-mcp
```

You can pass the key inline through `GITHUB_APP_PRIVATE_KEY` instead. Escaped
`\n` sequences are normalized automatically.

GitHub App installations are also read-only by default. To enable their write
tools:

```bash
GITHUB_WRITE_ENABLED=true
```

This explicit gate prevents an AI client from turning a broadly scoped
credential into write access by accident.

## Claude Desktop

Add the server to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "github-pr-control": {
      "command": "npx",
      "args": ["-y", "github-pr-control-mcp"],
      "env": {
        "GITHUB_READ_TOKEN": "github_pat_read_only"
      }
    }
  }
}
```

Restart Claude Desktop. Try:

> List open PRs in `owner/repo`, inspect the newest one's diff and comments,
> then summarize the highest-risk changes. Do not write to GitHub.

To enable reviews, add a tightly scoped `GITHUB_WRITE_TOKEN` to `env`.

## Cursor

Create `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "github-pr-control": {
      "command": "npx",
      "args": ["-y", "github-pr-control-mcp"],
      "env": {
        "GITHUB_READ_TOKEN": "${env:GITHUB_READ_TOKEN}"
      }
    }
  }
}
```

Reload Cursor after saving the file.

## Opt-in review prompts

The server exposes two built-in MCP prompts. They appear in clients that support
MCP prompts and run only when a user selects them:

- `triage_pull_request` gathers metadata, the relevant diff, and existing
  comments, then returns a read-only risk and next-action summary.
- `review_pull_request` performs an evidence-first review and drafts
  line-specific findings without publishing anything.

Both prompts accept `owner`, `repo`, `pull_number`, and an optional `focus`.
Neither prompt authorizes write tools. Publishing comments, labels, approvals,
or change requests always requires a separate explicit instruction and enabled
write credentials.

## Tool examples

### Paginate a repository with more than 50 PRs

```json
{
  "owner": "microsoft",
  "repo": "vscode",
  "state": "open",
  "per_page": 50,
  "max_pages": 3
}
```

### Read a large diff in chunks

First call:

```json
{
  "owner": "owner",
  "repo": "repo",
  "pull_number": 42,
  "offset": 0,
  "limit": 2000
}
```

Pass the returned `next_offset` into the next call until it is `null`.

### Post a multi-line inline comment

```json
{
  "owner": "owner",
  "repo": "repo",
  "pull_number": 42,
  "body": "This branch can return a stale value when the cache is empty.",
  "path": "src/cache.ts",
  "start_line": 18,
  "start_side": "RIGHT",
  "line": 23,
  "side": "RIGHT"
}
```

If `commit_id` is omitted, the server resolves the current PR head SHA just
before posting.

## Development

```bash
git clone https://github.com/nexicturbo/github-pr-control-mcp.git
cd github-pr-control-mcp
npm install
npm run ci
```

The test suite covers multi-page pagination, bounded diff traversal, read/write
separation, opt-in prompt registration, review submission, label preservation,
configuration validation, and rate-limit error messages.

## Security notes

- Tokens and private keys are read only from environment variables or an
  explicitly configured private-key path.
- Credentials are never returned through MCP tool results.
- No subprocess or shell command is invoked by the server.
- Write tools are disabled unless the operator explicitly opts in.
- Use the narrowest repository and permission scope possible.

## License

[MIT](LICENSE)