English | Русский

pr-review-mcp

Unified MCP control plane for AI pull request reviews on GitHub.

Modern pull requests often attract multiple AI reviewers, but their comments arrive in different formats, different places, and different timelines. pr-review-mcp turns that noise into one MCP-native workflow: it normalizes review output from seven agent sources, exposes 19 focused tools, and adds orchestration primitives for parallel review handling.

If you use Claude Code, Claude Desktop, or another MCP client to process GitHub reviews, this server gives you one place to list findings, inspect details, invoke agents, wait for them server-side, and coordinate worker agents without building your own review pipeline.

What's New in v0.3.0

• pr_await_reviews adds a server-side wait loop for AI reviews, so clients no longer need to poll GitHub manually while agents finish posting.

• pr_invoke now returns since, invokedAgentIds, and awaitHint, making the handoff into pr_await_reviews explicit and reliable.

• Claude Code integration is stronger with skills/review/SKILL.md, a dedicated skill that wraps /pr:review into an autonomous review workflow.

• CI now runs build, tests, and coverage on Node 20 and 22 through GitHub Actions.

• Coverage reporting is part of the release baseline with @vitest/coverage-v8; v0.3.0 records 225 Vitest test cases and a 51.7% statement coverage baseline.

• Qodo completion tracking is more accurate because persistent issue comments are detected via updated_at, not only created_at.

• Agent status polling was simplified by extracting shared logic into fetchAgentStatusForAgents, removing duplicated code paths.

• Ten dependency vulnerabilities were resolved as part of the release hardening work.

Related MCP server: code-review-mcp-server

Features

• Automates multi-agent PR review workflows with 19 MCP tools, 3 prompts, and 1 dynamic PR resource.

• Eliminates review-source fragmentation by normalizing comments from CodeRabbit, Gemini, Copilot, Sourcery, Qodo, Codex, and Greptile.

• Prevents polling loops in clients with pr_await_reviews, a server-side monitor for agent completion.

• Coordinates parallel workers safely with file-level partition claiming, progress reporting, and orchestration status checks.

• Surfaces machine-readable review data through structured outputs on key tools such as pr_summary, pr_list, pr_get, pr_get_work_status, and pr_progress_check.

• Supports local and shared deployments through stdio by default and StreamableHTTP with pr-review-mcp --http or pr-review-mcp --http 8080.

• Protects operational workflows with confirmation flows for destructive actions such as merge and coordination reset.

• Ships with Claude Code assets including .claude-plugin/plugin.json, .mcp.json, and the review skill for slash-command driven orchestration.

Architecture

graph TD
    Client["MCP Client<br/>Claude Code / Claude Desktop / Inspector"]

    Client -->|stdio| Server
    Client -->|StreamableHTTP| Server

    subgraph Server["pr-review-mcp v0.3.0"]
        subgraph Interface["MCP Interface"]
            Resource["Resource<br/>pr://{owner}/{repo}/{pr}"]
            PromptReview["Prompt<br/>review"]
            PromptReviewBg["Prompt<br/>review-background"]
            PromptSetup["Prompt<br/>setup"]
        end

        subgraph Analysis["Analysis Tools (7)"]
            T1["pr_summary"]
            T2["pr_list_prs"]
            T3["pr_list"]
            T4["pr_get"]
            T5["pr_changes"]
            T6["pr_poll_updates"]
            T7["pr_await_reviews"]
        end

        subgraph Action["Action Tools (6)"]
            T8["pr_invoke"]
            T9["pr_resolve"]
            T10["pr_labels"]
            T11["pr_reviewers"]
            T12["pr_create"]
            T13["pr_merge"]
        end

        subgraph Orchestration["Orchestration Tools (6)"]
            T14["pr_claim_work"]
            T15["pr_report_progress"]
            T16["pr_get_work_status"]
            T17["pr_reset_coordination"]
            T18["pr_progress_update"]
            T19["pr_progress_check"]
        end

        Monitor["ReviewMonitor<br/>server-side wait + backoff"]
        Extractors["Extractors<br/>severity / prompt / nitpick / multi-issue"]
        Adapters["Adapters<br/>Qodo / Greptile"]
        State["Coordination State<br/>partitions / progress / phases"]
    end

    PromptReview --> T8
    PromptReview --> T14
    PromptReview --> T18
    PromptReviewBg --> T18
    PromptSetup --> T8
    Resource --> T1
    Analysis --> Monitor
    Analysis --> Extractors
    Action --> Adapters
    Orchestration --> State
    Monitor --> State

    Server --> GitHub["GitHub GraphQL + REST API"]
    State --> Workers["Parallel Worker Agents"]

Tools

Analysis

Action

Orchestration

Prompts

Resources

pr://{owner}/{repo}/{pr} is a dynamic MCP resource that returns pull request metadata and a current review summary in one JSON payload. Use it when a client needs a machine-readable snapshot without issuing multiple tool calls.

Example URI:

pr://thebtf/pr-review-mcp/2

Returned data includes PR metadata such as title, state, author, branch names, mergeability, review decision, timestamps, and the same summary dimensions exposed by pr_summary.

Quick Start

1. Install the server:

   npm install -g pr-review-mcp

2. Add it to your MCP client:

   {
     "mcpServers": {
       "pr": {
         "command": "pr-review-mcp",
         "env": {
           "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
         }
       }
     }
   }

3. Verify the binary and version:

   pr-review-mcp --version

Expected output:

pr-review-mcp v0.3.0

Installation

Prerequisites

• Node.js >=20.0.0

• A GitHub Personal Access Token with repo scope

• An MCP client such as Claude Code, Claude Desktop, or MCP Inspector

Global npm install

npm install -g pr-review-mcp

Verify the install

pr-review-mcp --version

MCP client configuration

Use the globally installed binary in your client config:

{
  "mcpServers": {
    "pr": {
      "command": "pr-review-mcp",
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Local clone alternative

git clone https://github.com/thebtf/pr-review-mcp.git
cd pr-review-mcp
npm install
npm run build

When running from a clone, point your client at the built entry point:

{
  "mcpServers": {
    "pr": {
      "command": "node",
      "args": ["D:/path/to/pr-review-mcp/dist/index.js"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

HTTP mode

Start a StreamableHTTP server on the default port:

pr-review-mcp --http

Or specify a port explicitly:

pr-review-mcp --http 8080

Upgrading

From v0.2.x to v0.3.0

• Update the package:

  npm install -g pr-review-mcp@0.3.0

• If your client automation waits for agents, switch from manual polling loops to the new pattern:

  1. Call pr_invoke

  2. Read since and invokedAgentIds from its response

  3. Pass those values into pr_await_reviews

• If you copied older README examples, migrate repository config to the nested format actually consumed by pr_invoke:

  {
    "version": 1,
    "invoke": {
      "agents": ["coderabbit", "gemini", "codex"],
      "defaults": {
        "focus": "best-practices",
        "incremental": true
      }
    }
  }

• Claude Code users can now rely on skills/review/SKILL.md for a richer /pr:review workflow.

• CI now validates build, tests, and coverage on Node 20 and 22, so local compatibility checks should target the same matrix.

Configuration

Environment variables

Valid agent IDs are coderabbit, sourcery, qodo, gemini, codex, copilot, and greptile.

Repository config

Create .github/pr-review.json in the reviewed repository to define repository-specific defaults:

{
  "version": 1,
  "invoke": {
    "agents": ["coderabbit", "gemini", "codex"],
    "defaults": {
      "focus": "best-practices",
      "incremental": true
    }
  }
}

Config resolution order is:

1. .github/pr-review.json

2. PR_REVIEW_AGENTS and PR_REVIEW_MODE

3. Built-in defaults (coderabbit, sequential)

invoke.defaults maps directly to the options accepted by pr_invoke, so you can preconfigure values such as focus and incremental at the repository level.

Usage

Workflow 1: Inspect a single PR

Use the analysis tools to summarize and drill into the review state:

{
  "name": "pr_summary",
  "arguments": {
    "owner": "thebtf",
    "repo": "pr-review-mcp",
    "pr": 2
  }
}

Then list unresolved findings:

{
  "name": "pr_list",
  "arguments": {
    "owner": "thebtf",
    "repo": "pr-review-mcp",
    "pr": 2,
    "resolved": false
  }
}

Workflow 2: Invoke agents and wait server-side

Trigger one or more AI reviewers:

{
  "name": "pr_invoke",
  "arguments": {
    "owner": "thebtf",
    "repo": "pr-review-mcp",
    "pr": 2,
    "agent": "all"
  }
}

Use the returned since and invokedAgentIds in pr_await_reviews:

{
  "name": "pr_await_reviews",
  "arguments": {
    "owner": "thebtf",
    "repo": "pr-review-mcp",
    "pr": 2,
    "since": "2026-03-28T10:00:00.000Z",
    "agents": ["coderabbit", "gemini"],
    "timeoutMs": 600000,
    "pollIntervalMs": 30000
  }
}

Workflow 3: Run an orchestrated parallel review

In Claude Code, start the orchestrator:

/pr:review 2

Under the hood, the prompt uses orchestration tools such as pr_claim_work, pr_report_progress, pr_progress_update, and pr_progress_check to distribute unresolved comment partitions across worker agents and track progress until review handling is complete.

Claude Code Integration

The repository ships with Claude Code assets:

• .claude-plugin/plugin.json declares the packaged plugin metadata and MCP server bootstrap.

• .mcp.json provides an MCP server config that points at the built dist/index.js.

• skills/review/SKILL.md defines the review skill used by /pr:review.

Available slash commands:

• /pr:review

• /pr:review-background

• /pr:setup

Minimal Claude Code configuration with the global binary:

{
  "mcpServers": {
    "pr": {
      "command": "pr-review-mcp",
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Agent Sources

Qodo and Greptile are handled through dedicated adapters because they do not behave like simple inline review-only sources.

Troubleshooting

GITHUB_PERSONAL_ACCESS_TOKEN is missing

The server checks prerequisites on startup and exits early if the token is not configured. Add the token to the env block of your MCP server entry and restart the client.

.github/pr-review.json seems ignored

pr_invoke only reads the nested config under invoke.agents and invoke.defaults. Invalid JSON falls back to default agents, so validate the file shape before assuming repository config is active.

HTTP mode does not start

Use the packaged CLI entry point:

pr-review-mcp --http

Or:

pr-review-mcp --http 8080

If you run from a clone instead, build first and invoke node dist/index.js --http.

An agent does not appear to respond

• Confirm the agent is enabled through .github/pr-review.json or PR_REVIEW_AGENTS.

• Check whether the agent already reviewed the PR; pr_invoke skips reviewed agents unless force is set.

• Use pr_await_reviews for a blocking wait or pr_poll_updates if your client needs periodic status refreshes.

• For Qodo, remember that new activity may update one persistent issue comment rather than create fresh review threads.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md for setup, validation, and PR submission guidance.

License

MIT. See LICENSE.