squad-mcp

An MCP server that reviews your code changes with four specialist agents running in parallel — for a fraction of the cost of doing it naively.

The problem

Ask an AI coding agent to "review this PR, write tests, update the docs, and check for risky changes" and it usually does these one at a time — reading the whole codebase again for each step. That's slow and it burns a lot of tokens (which means it costs more).

What squad-mcp does

You call one tool, dev_squad_process, with a repo path and a task description. Behind the scenes:

1. It fetches the relevant context once (git diff + architecture summary) instead of letting every agent re-read the codebase separately.
2. A cheap model decides which specialists are actually needed — no point running a Test Agent on a comment-only change.
3. The specialists that are needed (Docs, Test, Refactor, Review) run in parallel, each using the model that fits the job — a fast/cheap model for simple tasks, a stronger one for anything that needs real judgment.
4. Everything comes back as one combined report with a diff you can apply, plus a cost breakdown.

It doesn't scan your codebase from scratch — it queries an existing indexed code graph (codebase-memory-mcp) for just the structure it needs. squad-mcp doesn't reimplement that part; it builds the orchestration and cost-optimization layer on top of it.

Example

Input (calling dev_squad_process from Claude Code or any MCP client):

{
  "repo_path": "/Users/user/projects/my-python-app",
  "task_description": "Review the recent changes in core/auth.py, suggest unit tests, and check for refactor opportunities.",
  "target": "staged"
}

Output (trimmed):

# squad-mcp — Pipeline Report

**Total cost:** $0.0244 | **Estimated savings:** 83.5% vs. running everything on Sonnet without caching
**Duration:** 3.42s

## Docs Agent (claude-haiku-4-5-20251001)
Added a missing docstring to `authenticate_user`.

```diff
 def authenticate_user(username, password):
+    """Authenticates a user against the database."""
      return db.query(username, password)
```

## Test Agent (claude-haiku-4-5-20251001)
Added edge-case tests (empty password, SQL injection input).

## Refactor Agent (claude-sonnet-5)
Found a timing-attack risk in the password comparison — suggested `secrets.compare_digest`.

## Review Agent
Skipped — triage determined this change carries no architectural risk.

How it's put together

graph TD
    User([Claude Code / User]) -->|dev_squad_process| Server[squad-mcp]
    Server --> Fetcher[Context Fetcher]
    Fetcher -->|one query| Graph[codebase-memory-mcp]
    Fetcher --> Triage{Triage}
    Triage -->|skip what's not needed| Router[Model Router]
    Router --> Docs[Docs Agent]
    Router --> Test[Test Agent]
    Router --> Refactor[Refactor Agent]
    Router --> Review[Review Agent]
    Docs & Test & Refactor & Review --> Report[Combined report + cost log]
    Report --> User

Setup

# 1. Install codebase-memory-mcp (squad-mcp depends on it)
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

# 2. Clone and install squad-mcp
git clone https://github.com/MustafaBozann/squad-mcp.git
cd squad-mcp
python -m venv .venv
.venv\Scripts\activate      # Windows
# source .venv/bin/activate # macOS/Linux
pip install -e .[dev]

# 3. Add your API key
copy .env.example .env      # Windows
# cp .env.example .env      # macOS/Linux
# then fill in ANTHROPIC_API_KEY

Add it to Claude Desktop / Claude Code by putting this in your MCP config:

{
  "mcpServers": {
    "squad-mcp": {
      "command": "C:\\path\\to\\squad-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\squad-mcp\\squad_mcp\\mcp_server.py"]
    }
  }
}

Does it actually save money?

The numbers below are from a simulated benchmark (benchmarks/run_benchmark.py). Run it yourself with --real (and a real API key) to get measured numbers on your own repo instead of trusting mine:

Scenario	Naive (tokens / cost)	squad-mcp (tokens / cost)	Reduction
Small PR (2 files)	11,600 / $0.054	5,800 / $0.010	80.8%
Medium PR (10 files)	63,200 / $0.228	47,400 / $0.036	84.2%
Large PR (30+ files)	226,000 / $0.750	226,000 / $0.138	81.5%

How this compares

	CodeRabbit	Qodo	squad-mcp
Code graph context	No (diff-only)	Partial	Yes
Parallel specialist agents	No	No	Yes
Fully local mode (Ollama)	No	No	Yes
Per-run cost breakdown	No	No	Yes
Language support (v1)	Multiple	Multiple	Python only

Known limitations

• v1 only handles Python repositories.
• The Test Agent proposes tests, it doesn't run them yet.
• The GitHub Action in examples/ is a template, not a published reusable action.
• Benchmarks are simulated by default — see --real above.

Built with

The full build log (what was built in what order, and why) is in docs/DEVELOPMENT.md.

License

MIT — see LICENSE.