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

Tool	Use it for
review_git_diff(diff)	Output of git diff. Reviewed per file.
review_code_file(filepath)	A file on disk. Language detected from the extension.
review_code_snippet(code, language="python")	A piece of code not yet in a file.

Providers

Provider	Set LLM_PROVIDER to	Connection	Notes
Ollama	ollama (default)	local server, no key	Code stays on your machine
OpenAI	openai	OPENAI_API_KEY	Also any OpenAI-compatible API via OPENAI_BASE_URL
Anthropic	anthropic	ANTHROPIC_API_KEY
OpenRouter	openrouter	OPENROUTER_API_KEY	One key, many models — see openrouter.ai/models
OpenAI-compatible (llama.cpp, vLLM, LM Studio)	openai + OPENAI_BASE_URL	usually no key	Local servers generally ignore the key

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:

Model	Pull with	Notes
Qwen2.5-Coder	ollama pull qwen2.5-coder:7b	Strong all-round code model; :14b/:32b if you have the VRAM
Qwen3-Coder	ollama pull qwen3-coder	Newer Qwen coding model
DeepSeek-Coder V2	ollama pull deepseek-coder-v2	Good multi-language coverage
Codestral	ollama pull codestral	Mistral's code model
CodeLlama	ollama pull codellama	Widely available baseline
Llama 3.2 3B	ollama pull llama3.2:3b	The default — small and fast, lighter reviews

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

Variable	Default	Description
LLM_PROVIDER	ollama	ollama, openai, anthropic, or openrouter
OLLAMA_BASE_URL	http://localhost:11434	Ollama server URL
OLLAMA_MODEL	llama3.2:3b	Ollama model name
OPENAI_API_KEY	—	OpenAI API key (optional for local servers)
OPENAI_MODEL	gpt-4o-mini	OpenAI model name
OPENAI_BASE_URL	—	Custom OpenAI-compatible endpoint
ANTHROPIC_API_KEY	—	Anthropic API key
ANTHROPIC_MODEL	claude-sonnet-4-6	Anthropic model name
OPENROUTER_API_KEY	—	OpenRouter API key
OPENROUTER_MODEL	qwen/qwen3-coder-30b-a3b-instruct	OpenRouter model slug
OPENROUTER_BASE_URL	https://openrouter.ai/api/v1	OpenRouter endpoint
MAX_TOKENS	4096	Max tokens per response
TEMPERATURE	0.3	Sampling temperature (0–2)
REQUEST_TIMEOUT	120	Per-request timeout in seconds
MAX_INPUT_CHARS	100000	Reject inputs larger than this
STREAM	true	Stream responses; falls back to a single request if unsupported
CUSTOM_PROMPT	—	Override the review prompt (must contain {code} and {language})

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.