code-quality-mcp

Stop asking your LLM if your Python is clean. Let it actually check.

An MCP server that gives Claude, Cursor, VS Code (or any MCP-compatible client) a real, deterministic view of your Python code quality — powered by the tools you already trust: flake8, mypy, McCabe, and vulture.

No more "looks good to me" from an LLM that never ran a linter. This is ground truth.

---

Why

LLMs hallucinate code reviews. They miss style violations, invent complexity numbers, and confidently declare your dead code "actively used."

code-quality-mcp plugs the gap: it runs the canonical Python quality tools and hands the LLM a clean, structured report. The model stops guessing and starts citing.

It also ships with a hard instruction baked into the server: never modify, refactor, or fix your code unless you explicitly ask. It reports. You decide.

---

What it gives you

Tool	What it checks	MCP function
flake8	PEP8 style, line length, unused imports	analyze_style
McCabe	Cyclomatic complexity per function	analyze_complexity
vulture	Dead code, unused variables and functions	analyze_dead_code
mypy	Static type errors	analyze_types
All-in-one	flake8 + McCabe + vulture, parallel	analyze_all
Snippet mode	Paste raw source, no file needed	analyze_content

Reports come back as markdown tables — readable for you, parseable for the model.

---

Install

git clone https://github.com/Javier-Morenosa/code-quality-mcp.git
cd code-quality-mcp
pip install -e .

Requires Python 3.10+.

---

Wire it up

Cursor

Add to your Cursor MCP settings (or copy cursor_mcp.json):

{
  "mcpServers": {
    "code-quality": {
      "command": "python",
      "args": ["-m", "code_quality_mcp.server"],
      "env": {
        "PYTHONPATH": "C:/path/to/code-quality-mcp/src"
      }
    }
  }
}

VS Code

See vscode_mcp.json for a ready-to-use config.

Claude Code

claude mcp add code-quality -- python -m code_quality_mcp.server

---

Use it

Once the server is wired up, just talk to your LLM:

"Run a full quality analysis on src/my_module.py."

"Is there dead code in this project?"

"Which functions are too complex?"

The model will call the right tools, get real output from real linters, and give you a report grounded in facts — not vibes.

Pro tip

Call set_workspace once at the start of a session to point the server at your project root. After that, you can pass relative paths and everything Just Works.

---

What it will NOT do

By design, this server is read-only. It will not:

• Edit your files
• Refactor your code
• Auto-fix style issues
• Suggest changes unless you explicitly ask for them

If you want fixes, run black, ruff --fix, or ask your LLM directly. This server's job is to tell the truth about your code, nothing more.

---

Roadmap

• ruff backend as a faster drop-in for flake8
• Per-file complexity heatmap
• Configurable rule sets via pyproject.toml

---

License

MIT. Use it, ship it, fork it.