mcp-agent-review

An MCP (Model Context Protocol) server that provides agentic code review powered by OpenAI-compatible models. Designed for use with Claude Code.

Features

• Deep analysis — focuses on logic errors, architecture issues, doc-code consistency, and security risks (not style/lint)
• Agentic review — the model can read files, grep code, check git blame, explore project structure, and search git history to verify findings
• False-positive suppression — mandatory tool verification, confidence rating, and self-critique phase
• Intent-aware review — pass task_description to catch mismatches between intent and implementation
• Directed focus — pass review_focus to get deeper analysis on a specific dimension (security, performance, concurrency, etc.)
• Any OpenAI-compatible API — works with GitHub Models (free), OpenAI, Azure OpenAI, or any compatible provider
• Zero config for git repos — auto-detects diffs, reads CLAUDE.md for project context
• Sensitive file protection — blocks access to .env, *.pem, *.key, credentials, and other sensitive files

Installation

# From PyPI
pip install mcp-agent-review

# From source
git clone https://github.com/lzx1413/mcp-agent-review
cd mcp_agent_review
pip install .

Claude Code Integration

Add to your Claude Code settings (~/.claude.json or .claude/settings.json):

GitHub Models (free)

{
  "mcpServers": {
    "code-review": {
      "command": "mcp-agent-review",
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}

OpenAI (or other providers)

{
  "mcpServers": {
    "code-review": {
      "command": "mcp-agent-review",
      "env": {
        "OPENAI_API_KEY": "your-api-key",
        "OPENAI_BASE_URL": "https://api.openai.com/v1",
        "REVIEW_MODEL": "gpt-4o"
      }
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | GITHUB_TOKEN | Yes* | — | GitHub personal access token (free via GitHub Models) | | OPENAI_API_KEY | Yes* | — | API key for OpenAI or compatible provider (takes priority over GITHUB_TOKEN) | | OPENAI_BASE_URL | No | https://models.github.ai/inference | Base URL for the API | | REVIEW_MODEL | No | gpt-4o | Model to use for review | | MAX_TOOL_ROUNDS | No | 8 | Max agentic tool-use rounds | | MAX_FILE_LINES | No | 1000 | Max lines to read per file |

*One of GITHUB_TOKEN or OPENAI_API_KEY is required.

Tool Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | diff | No | Custom diff string. If omitted, auto-reads from git diff | | base | No | Base branch/commit for PR review (e.g. main) | | task_description | No | What the changes are intended to accomplish (e.g. fix race condition in pool). Enables intent-vs-implementation mismatch detection | | review_focus | No | Specific dimension to prioritize (e.g. security, performance, concurrency safety). Deeper analysis on this area |

Usage

Once configured in Claude Code, the review_code tool is available:

• Auto-detect changes: just call review_code with no arguments — it reads git diff
• PR review: pass base='main' to review all changes since diverging from main
• Custom diff: pass a diff string directly via the diff parameter
• Intent-aware review: pass task_description to describe what the changes are for — helps catch gaps between intent and implementation
• Directed focus: pass review_focus (e.g. 'security', 'performance') to get deeper analysis on a specific dimension

Example prompts in Claude Code

Review my current changes

Review the changes on this branch against main

Review my changes, the task is to fix the race condition in the connection pool, focus on concurrency safety

How It Works

1. Context collection — reads CLAUDE.md, git log, commit messages, and full source of changed files
2. Agentic review — sends context + diff to the model, which can use tools (read_file, grep_code, git_blame, list_files, search_git_history, find_test_files) to investigate
3. Self-critique — a second pass filters out low-confidence or speculative findings
4. Structured output — returns findings with confidence level, category, file location, and explanation

License

MIT