Mutmut

Mutmut MCP is an MCP server that orchestrates mutation testing with mutmut for Python projects. It provides programmatic APIs to run mutation tests, analyze results, and guide test coverage improvements, making it easier to automate and integrate mutation testing into your workflows.

How to use

You run the Mutmut MCP server locally and connect to it from an MCP client to perform mutation testing tasks. Start the server using one of the supported runtime hosts, then use the available MCP tools to execute mutations, review results, and refine tests. You can run tests for a specific module or package, inspect surviving mutations, generate coverage recommendations, and re-run mutation tests as needed.

How to install

Choose your preferred installation flow and follow the steps below.

# Option 1: Manual installation (Python environment)
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install mcp[cli] mutmut

# Start the MCP server locally with Python (standard runtime)
python mutmut_mcp.py

# Alternative: Run via uv (uvx) for asynchronous execution
uv run --with mcp --with mutmut mutmut_mcp.py

If you prefer a package-based automation flow, you can also install via Smithery (for client-side setup):

npx -y @smithery/cli install @wdm0006/mutmut-mcp --client claude

Available tools

run_mutmut

Execute mutation tests on a target module or package and capture results.

show_results

Display overall mutation testing results and statistics.

show_survivors

List mutations that survived the tests, indicating coverage gaps.

generate_test_suggestion

Provide recommendations on where tests should be added or strengthened.

rerun_mutmut_on_survivor

Rerun mutation tests specifically on surviving mutations to verify changes.

clean_mutmut_cache

Clear the mutmut cache to ensure fresh mutation runs.