# PR Reviewer MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that connects Claude to GitHub, allowing it to list repositories, browse open pull requests, and inspect PR diffs — all from within Claude Code.

## Prerequisites

- Python 3.11+
- [uv](https://docs.astral.sh/uv/getting-started/installation/) — fast Python package manager
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed (`npm i -g @anthropic-ai/claude-code`)
- A GitHub Personal Access Token with `repo` scope

## Setup

### 1. Clone the repository

```bash
git clone https://github.com/subhamyadav580/pr-reviewer.git
cd pr-reviewer
```

### 2. Install dependencies

```bash
uv sync
```

This creates a `.venv` and installs all pinned dependencies from `uv.lock`.

### 3. Get a GitHub Personal Access Token

Go to **GitHub → Settings → Developer settings → Personal access tokens** and create a token with at minimum the `repo` scope (add `read:org` if your org repos are private).

### 4. Register the MCP server with Claude Code

Run this once — it registers the server at user scope so it's available in every project:

```bash
claude mcp add pr-reviewer -s user \
  -e GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx \
  -e GITHUB_ORG=your-github-org-name \
  -- /absolute/path/to/pr-reviewer/.venv/bin/python \
     /absolute/path/to/pr-reviewer/main.py
```

Replace:
- `ghp_xxxxxxxxxxxxxxxxxxxx` — your GitHub PAT
- `your-github-org-name` — the GitHub org you want to query (e.g. `my-company`)
- `/absolute/path/to/pr-reviewer` — the full path where you cloned this repo

Verify it was registered:

```bash
claude mcp list
```

You should see `pr-reviewer` in the output.

### 5. (Optional) Install the `/review-pr` slash command

The repo ships with a `review-pr.md` slash command that gives Claude a structured, step-by-step review workflow. Copy it into your global Claude commands folder:

```bash
mkdir -p ~/.claude/commands
cp /absolute/path/to/pr-reviewer/review-pr.md ~/.claude/commands/review-pr.md
```

Now in any Claude Code session type `/review-pr` and Claude will:
1. List all org repositories for you to pick from
2. Show open PRs in the selected repo
3. Fetch the PR details and diff
4. Post a structured review with Blockers / Suggestions / Positives and a merge recommendation

## Available MCP Tools

| Tool | Description |
|------|-------------|
| `list_org_repositories` | Lists all repositories in the configured GitHub org |
| `list_open_pull_requests(repo_full_name)` | Lists open PRs for a repo (e.g. `"my-org/my-repo"`) |
| `get_pull_request_details(repo_full_name, pr_number)` | Returns PR metadata: title, body, author, file count, additions/deletions |
| `get_pull_request_diff(repo_full_name, pr_number)` | Returns per-file diffs with the raw unified diff patch |

## Usage

Once registered you can talk to Claude naturally:

> "List all open PRs in my org"
> "Show me the diff for PR #42 in my-org/backend"
> "Review PR #15 in my-org/frontend — flag bugs and style issues"

Or use the `/review-pr` slash command for a guided, structured review flow.

## Project Structure

```
pr-reviewer/
├── main.py          # MCP server — all tool definitions
├── review-pr.md     # Slash command for Claude Code (/review-pr)
├── pyproject.toml   # Project metadata and dependencies
├── uv.lock          # Pinned dependency versions
├── .python-version  # Python version pin (3.11)
└── .env.example     # Template — copy to .env for local use
```

## Claude Desktop

If you prefer Claude Desktop instead of the CLI, add this to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "pr-reviewer": {
      "command": "/absolute/path/to/pr-reviewer/.venv/bin/python",
      "args": ["/absolute/path/to/pr-reviewer/main.py"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx",
        "GITHUB_ORG": "your-github-org-name"
      }
    }
  }
}
```

Restart Claude Desktop after saving.

## Development

Run the server manually to test it:

```bash
uv run python main.py
```

To add a new tool, define a function decorated with `@mcp.tool()` in `main.py`. FastMCP exposes it to Claude automatically.