Mutmut MCP
Based on the schema, this MCP server supports core mutmut mutation-testing workflows for Python projects.
Run a full
mutmut runagainst a specified target, with optional extra CLI options and a virtualenv path.Show overall results from the last mutmut run.
List surviving mutations.
Rerun a specific surviving mutant or all survivors after test updates.
Show the diff/details for a named mutant.
Prioritize surviving mutants by likely materiality, filtering out log/debug-only changes.
Clean mutmut cache/state.
Note: the schema does not expose the README-mentioned project_path, background run/status/cancel, mutant_context, or mutation_score tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Mutmut MCP run mutation testing on my utils module"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Mutmut MCP
A Model Context Protocol (MCP) server for managing mutation testing with mutmut. This tool provides a set of programmatic APIs for running mutation tests, analyzing results, and improving test coverage in Python projects. It targets mutmut 3.x: mutants are named (mymodule.x_add__mutmut_1), reported per mutant with a status (killed / survived / no tests / timeout / suspicious / skipped / segfault), and configured through [tool.mutmut] in pyproject.toml.
Features
Run mutation testing sessions against the projects mutmut 3.x is configured for (
source_pathsin[tool.mutmut]), not per-target CLI flagsShow results per mutant name and status, and list surviving mutations, including a labelled section for mutants no test covers
Show the code diff for a single mutant and rerun one mutant, all survivors, or the survivors no test covers
Rank survivors and uncovered mutants by likely materiality so an agent knows what to look at first
Clean mutmut's per-project state (
mutants/and the legacy cache) without touching other projectsSerialize concurrent runs: two mutmut operations against the same project never race; the second gets a structured busy error
Classify every failure by its explicit channel — non-zero exit, exception, or local validation — never by sniffing output text
Practices what it preaches: this repository's own CI runs the server against itself with
source_paths = ["mutmut_mcp.py"]and fails on mutation-strength regressions (see How this server tests itself)
Related MCP server: MCP Python Server
Install
# Run directly from GitHub (no install needed)
uvx --from git+https://github.com/wdm0006/mutmut-mcp mutmut-mcp
# Or install from source
git clone https://github.com/wdm0006/mutmut-mcp
cd mutmut-mcp
uv sync
uv run mutmut_mcp.pyInstalling via Smithery
To install mutmut-mcp for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @wdm0006/mutmut-mcp --client claudeMCP Client Configuration
{
"mcpServers": {
"mutmut": {
"command": "uvx",
"args": ["--from", "git+https://github.com/wdm0006/mutmut-mcp", "mutmut-mcp"]
}
}
}API / Tools
The following tools are available:
run_mutmut(target, options="", venv_path=None, project_path=None)– Run a mutation testing session (mutmut run) for the project; survivors are expected and are a result, not a failurestart_mutmut_run(target="", options="", venv_path=None, project_path=None)– Startmutmut runin a background thread and return{run_id, state}immediately; holds the project's write lock until it ends (other write tools return the busy error)mutmut_run_status(run_id)–{state: running|finished|failed, elapsed_s, exit_failed, output_tail, progress}for a background run; unknown ids return an error (the newest 20 jobs are kept, in memory only)cancel_mutmut_run(run_id)– Terminate a background run (SIGTERM, then SIGKILL), free the project lock and mark itcancelled; mutmut state may be partial afterwards. Finished or unknown ids are a no-op with a messageshow_results(venv_path=None, project_path=None)– Show the last campaign's results per mutant name and statusshow_survivors(venv_path=None, project_path=None)– List surviving mutations, plus a labelled section for mutants no test coversrerun_mutmut_on_survivor(mutation_id=None, venv_path=None, project_path=None)– Rerun a specific mutant (mutmut run <name>) or all surviving mutantsclean_mutmut_cache(venv_path=None, project_path=None)– Remove mutmut'smutants/state directory and legacy cache for the projectshow_mutant(mutation_id, venv_path=None, project_path=None)– Show the code diff and details for one named mutantmutant_context(mutation_id, venv_path=None, project_path=None)–{mutant_id, diff, tests, message}: the mutant's diff plus the pytest ids covering it (mutmut show+mutmut tests-for-mutant); an emptytestslist means no test covers itprioritize_survivors(venv_path=None, project_path=None)– Rank survivors and uncovered mutants by likely materiality, highest score firstmutation_score(venv_path=None, project_path=None)– Killed/total counts and the mutation score (nullwhen there are no results or the run is incomplete) from onemutmut results --all trueread
project_path
Every tool accepts an optional project_path: the directory containing the project's mutmut
configuration ([tool.mutmut] in pyproject.toml), its source, its tests, and mutmut's
mutants/ state directory. Mutmut runs with that directory as its working directory, and
clean_mutmut_cache removes state only from inside it.
Lock file
run_mutmut, start_mutmut_run, rerun_mutmut_on_survivor and clean_mutmut_cache take a
cross-process advisory lock on <project_path>/.mutmut-mcp.lock (created on first use, kept
outside mutants/ so cleaning does not delete it). A second MCP server, or any other process
holding that lock, makes these tools return the "already in progress" error instead of
corrupting mutmut's state; a plain terminal mutmut run does not take the lock. Read tools
never lock. If the file cannot be created (read-only project) the server falls back to its
in-process lock only. Add .mutmut-mcp.lock to your project's .gitignore.
Pass it whenever the server was not launched from the project directory — which is typical for
desktop MCP clients and uvx. Omitted, the tools fall back to the server process's working
directory, so existing calls behave as before. A project_path that is not an existing directory
returns an error without running mutmut or deleting anything.
venv_path
venv_path points at the virtual environment holding the project's mutmut (the tools use
<venv>/bin/mutmut, or <venv>\Scripts\mutmut.exe on Windows); omitted, mutmut is taken from
PATH. A relative venv_path is resolved against project_path when both are given, so the
common .venv form works:
{ "project_path": "/home/me/src/myproject", "venv_path": ".venv" }How this server tests itself
The repository's own [tool.mutmut] configuration points mutmut at the server module
(source_paths = ["mutmut_mcp.py"]), so CI runs the mutation-testing server against itself.
The campaign result is scored by scripts/mutation_budget.py, which reuses the server's own
strict results parser and fails the build when the number of undetected mutants (survived or
no tests) exceeds a fixed budget. The six allowed survivors are equivalent mutants, each
documented in docs/mutation-waivers.md; anything new is a
regression and must be killed by a named test or waived with a written reason.
Locally, the same loop is available via make mutate; make coverage enforces the measured
100% line-coverage floor, and make typecheck runs mypy.
License
This project is licensed under the MIT License. See LICENSE for details.
Available Tools
7 toolsclean_mutmut_cacheB
Clean mutmut cache using the mutmut CLI (if available), otherwise remove .mutmut-cache file. Returns the plain text output or confirmation message.
Inputs: venv_path. Returns: result
prioritize_survivorsA
Prioritize surviving mutants by likely materiality, filtering out log/debug-only changes and ranking by potential impact. Returns a sorted list of survivors with reasons for prioritization.
Inputs: venv_path. Returns: object
rerun_mutmut_on_survivorB
Rerun mutmut on specific surviving mutations or all survivors after test updates using the mutmut CLI. Returns the plain text output.
Inputs: mutation_id, venv_path. Returns: result
run_mutmutA
Run a full mutation testing session with mutmut on the specified target.
This tool initiates mutation testing on the given module or package. You can provide additional mutmut options as needed. The output includes a summary of mutations tested, including counts of killed, survived, and timed-out mutations. If a virtual environment path is provided, mutmut will be run using the binaries from that environment to ensure compatibility with project-specific dependencies.
Args: target (str): The module or package to run mutation testing on. options (str): Additional command-line options for mutmut (e.g., '--use-coverage'). Defaults to empty. venv_path (Optional[str]): Path to the project's virtual environment to use for running mutmut. Defaults to None.
Returns: str: Summary of the mutation testing run, or error message if the run fails.
Inputs: target (required), options, venv_path. Returns: result
show_mutantB
Show the code diff and details for a specific mutant using mutmut show. Args: mutation_id (str): The ID of the mutant to show. venv_path (Optional[str]): Path to the virtual environment, if any. Returns: str: The output of 'mutmut show <mutation_id>'.
Inputs: mutation_id (required), venv_path. Returns: result
show_resultsC
Display overall results from the last mutmut run using the mutmut CLI. Returns the plain text output.
Inputs: venv_path. Returns: result
show_survivorsC
List details of surviving mutations from the last mutmut run using the mutmut CLI. Returns the plain text output.
Inputs: venv_path. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a distinct purpose: run_mutmut initiates testing, show_results displays overall results, show_survivors lists survivors, show_mutant shows specific mutant details, rerun_mutmut_on_survivor retests survivors, prioritize_survivors ranks survivors, and clean_mutmut_cache manages cache. There is no overlap or ambiguity in functionality.
All tools follow a consistent snake_case naming pattern with clear verb_noun structures (e.g., run_mutmut, show_results, clean_mutmut_cache). The naming is predictable and readable throughout the set.
With 7 tools, this server is well-scoped for mutation testing with mutmut. Each tool serves a specific role in the workflow, from running tests to analyzing results, without being overly sparse or bloated.
The tool set provides complete coverage for the mutmut domain: it includes core testing (run_mutmut), result inspection (show_results, show_survivors, show_mutant), survivor management (rerun_mutmut_on_survivor, prioritize_survivors), and maintenance (clean_mutmut_cache). There are no obvious gaps in the mutation testing lifecycle.
Maintenance
Related MCP Connectors
A Model Context Protocol server for Wix AI tools
Model Context Protocol server for Studex tools, notifications, and profile integrations
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceA Model Context Protocol server that enables AI assistants like Claude to perform Python development tasks through file operations, code analysis, project management, and safe code execution.9MIT
- FlicenseNot gradedqualityDmaintenanceA Python-based implementation of the Model Context Protocol that enables communication between a model context management server and client through a request-response architecture.-
- AlicenseAqualityBmaintenanceA Model Context Protocol server that allows LLMs to interact with Python environments, execute code, and manage files within a specified working directory.10784 PyPI104MIT
- FlicenseAqualityNot gradedmaintenanceA Model Context Protocol server that allows LLMs to interact with Python environments, enabling code execution, file operations, package management, and development workflows.9-