codereview-mcp

An MCP server that lets an AI coding agent review code with a language model. Point it at a git diff, a file, or a snippet and it returns a structured review with severity levels. It works with any MCP client (Claude Code, Cursor, VS Code, Continue, Windsurf) and supports Ollama (local, the default), OpenAI, Anthropic, OpenRouter, and any OpenAI-compatible server (llama.cpp, vLLM, LM Studio, and similar).

With the default Ollama backend, code never leaves your machine.

What it does

• Reviews git diff output, parsing it per file and skipping binaries and deletions
• Reviews whole files, with language auto-detected from the extension (50+ languages)
• Reviews inline snippets in a language you specify
• Returns findings tagged by severity: CRITICAL, WARNING, SUGGESTION, NOTE
• Retries transient provider failures (rate limits, timeouts, 5xx) with backoff

It is a reviewer, not a gate. The output is advice from a model and should be read by a human, not wired straight into an automatic merge. See SECURITY.md for the threat model, including prompt injection.

Install

Requires Python 3.10+. Install from the repository:

pip install git+https://github.com/lfylow/codereview-mcp

Or from a clone:

git clone https://github.com/lfylow/codereview-mcp
cd codereview-mcp
pip install .

For the default local backend, install Ollama and pull a model. A coding-tuned model gives noticeably better reviews than a small general model:

ollama pull qwen2.5-coder:7b      # recommended
# or the smaller default, lighter on RAM:
ollama pull llama3.2:3b

Then run the server (it speaks MCP over stdio, so it's normally launched by a client rather than by hand):

codereview-mcp --model qwen2.5-coder:7b

To see which models are installed on your Ollama server:

codereview-mcp --list-models

Connect an agent

Claude Code

claude mcp add codereview-mcp -- codereview-mcp

To use a hosted provider, pass the environment through:

claude mcp add codereview-mcp --env LLM_PROVIDER=openai --env OPENAI_API_KEY=sk-... -- codereview-mcp

VS Code (Copilot) — .vscode/mcp.json

{
  "servers": {
    "codereview-mcp": { "type": "stdio", "command": "codereview-mcp" }
  }
}

Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "codereview-mcp": { "command": "codereview-mcp" }
  }
}

Continue / Windsurf

Both use the same shape as Cursor: an mcpServers entry with "command": "codereview-mcp". Add provider keys under an "env" object on that entry if you aren't using Ollama.

Once connected, ask the agent things like "review my staged changes" or "review src/auth.py" and it will call the matching tool.

Tools

Providers

Authentication is by API key. The hosted providers don't offer an official way to use an account subscription in place of an API key for programmatic API access, so that mode isn't supported.

# OpenRouter
LLM_PROVIDER=openrouter OPENROUTER_API_KEY=sk-or-... codereview-mcp

# local OpenAI-compatible server (e.g. LM Studio on :1234), no key needed
LLM_PROVIDER=openai OPENAI_BASE_URL=http://localhost:1234/v1 codereview-mcp --model my-local-model

Models

Review quality tracks the model. For local use, a coding-tuned model is worth the extra download:

Run codereview-mcp --list-models to see what's installed locally. Pick a model with --model, OLLAMA_MODEL, or the config file.

Configuration

Configuration is read from defaults, then a config file, then environment variables, then CLI flags — each layer overriding the previous one.

Environment variables

Config file

~/.config/codereview-mcp/config.yml on Linux/macOS (respects XDG_CONFIG_HOME), or %APPDATA%\codereview-mcp\config.yml on Windows:

llm_provider: ollama
ollama_model: llama3.2:3b
temperature: 0.2
max_tokens: 2048

CLI flags

codereview-mcp --help
codereview-mcp --version
codereview-mcp --provider openai --model gpt-4o
codereview-mcp --config /path/to/config.yml
codereview-mcp --list-models      # list installed Ollama models and exit
codereview-mcp --no-stream        # disable streaming
codereview-mcp --verbose

Example output

A review of a small Python file looks like this:

## Review: `src/database.py` (python)

🔴 CRITICAL — SQL injection
`f"SELECT * FROM users WHERE id = {user_id}"` interpolates user input into SQL.
Use a parameterized query: `cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))`

🟡 WARNING — connection never closed
The connection opened on line 2 is never closed. Use a context manager:
`with sqlite3.connect("users.db") as conn:`

🟢 SUGGESTION — use the built-in
`calculate_average` can be `sum(numbers) / len(numbers)`.

The exact wording depends on the model you run.

Troubleshooting

"connection refused" / transport errors — Ollama isn't running or isn't on the expected URL. Start it with ollama serve and check OLLAMA_BASE_URL.

Empty or low-quality reviews — small local models miss things. Try a larger model (OLLAMA_MODEL=qwen2.5-coder:7b) or a hosted provider.

"Input too large" — the file or diff exceeds MAX_INPUT_CHARS. Review a smaller chunk or raise the limit.

"API key is required" — set OPENAI_API_KEY or ANTHROPIC_API_KEY for the chosen provider.

Run with --verbose to see what the server is doing on stderr.

Limitations

• Review quality depends entirely on the backing model. Small local models are fast and

private but less thorough than large hosted ones.

• The tool reviews the added/changed lines of a diff with surrounding context, not the

full repository, so it can miss issues that span files.

• Output is non-deterministic and advisory. It is not a substitute for tests or human

review.

Development

git clone https://github.com/lfylow/codereview-mcp
cd codereview-mcp
pip install -e ".[dev]"

pytest
ruff check src/ tests/
ruff format --check src/ tests/
mypy

See CONTRIBUTING.md for more.

License

MIT — see LICENSE.