# Python MCP server and Claude Code plugin

> Run the local quelltest MCP server (pip install quelltest[mcp]) so Claude Code, Cursor or any MCP client can find gaps and write verified Python tests.

Canonical page: https://quelltest.com/docs/mcp

The Python package ships a local MCP server, `quelltest-mcp`, that lets a coding agent (Claude Code, Claude Desktop, Cursor or any MCP client) find untested requirements, write verified pytest tests, score the project and reproduce bugs without a terminal. It runs over stdio on your machine and makes no network calls. Use it when an agent works in a Python repository. For JavaScript and TypeScript, use the [npm MCP server](https://quelltest.com/docs/npm/agents.md).

This is different from the [Claude.ai connector](https://quelltest.com/docs/connector.md): the connector serves synced readiness reports to Claude.ai, while the MCP server lets an agent run quelltest against the repository it is working in.

## How do I set it up?

Install the extra:

```bash
pip install "quelltest[mcp]"
```

Register the server in your project's `.mcp.json` (Claude Code reads it automatically):

```json
{
  "mcpServers": {
    "quelltest": { "command": "quelltest-mcp" }
  }
}
```

Then ask the agent to "find untested edge cases in this project" and it will call the tools. The server can also be started as `python -m quell.mcp_server` or `quell mcp`.

## What tools does it expose?

| Tool | What it does |
| --- | --- |
| `find_edge_cases(path, sources?)` | Scan for documented requirements with no test. Read-only. Returns totals, coverage percent and the gap list with file and line. |
| `write_verified_tests(path)` | Generate a pytest test per gap, verify each through all five gates, and write only proven tests. Returns a summary and the report path. |
| `get_prs_score()` | Project score with tier and per-file breakdown. |
| `prove_file(file, function?)` | Coverage ratio for one file, optionally narrowed to one function. |
| `reproduce_bug(description, file?)` | Turn a bug description into a verified failing test. |

Every tool returns structured JSON and never raises: errors come back as `{"error": "..."}` so the agent can react.

## What is the Claude Code plugin?

The plugin bundles a skill that teaches Claude the workflows: when to scan, how to read the three buckets, what to do with flagged items.

```text
/plugin marketplace add quelltest/quelltest-lib
/plugin install quelltest@quelltest
```

Then use slash commands or plain English:

```text
/quelltest find src/
/quelltest fix src/payments/
/quelltest score
/quelltest reproduce "payment accepts zero amount"
```

## What about privacy?

The local MCP server makes no network calls and has no telemetry; source code, test bodies and results stay in the repository. The [connector](https://quelltest.com/docs/connector/privacy.md) is separate, opt-in, and transmits sanitized metrics only. The optional LLM fallback only runs if you configure it: see [LLM providers](https://quelltest.com/docs/configuration/llm-providers.md).

## How do I troubleshoot it?

- **"mcp package is required":** install the extra with `pip install "quelltest[mcp]"`.
- **Tools do not appear in Claude Code:** check that `.mcp.json` is at the project root and restart the session; `claude mcp list` should show `quelltest`.
- **Tests are not written:** a test that fails any gate, including the violation check, is discarded and never written. Look at the report for the reason.
