Log inSubmit server
Verdict MCP logo

Verdict MCP

Runs impact-selected Python checks in an isolated environment and returns compact verdicts with failure history.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Verdict MCP

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "verdict-mcp": {
      "command": "uvx",
      "args": [
        "verdict-mcp"
      ],
      "env": {
        "VERDICT_PROJECT": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

The verdict-mcp MCP server gives coding agents structured verification for Python and pytest projects instead of raw shell output. It selects tests from the working-tree diff, runs checks in a rootless Podman or Docker container, and returns typed results with stable failure fingerprints. Use it when agents need concise regressions, on-demand tracebacks, and historical context without mutating the host worktree. Ruff and mypy checks use the same verdict format.

Use cases

  • Run tests affected by a working-tree diff
  • Track whether a failure predates a code change
  • Inspect one failure traceback on demand
  • Normalize Ruff and mypy results
  • Execute checks without mutating the host worktree

Key features

  • Static-import-based test impact selection
  • Rootless Podman or Docker execution
  • Stable failure fingerprints
  • Pre-existing failure detection
  • On-demand traceback retrieval
  • Ruff and mypy verdict normalization

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

13/13 checks healthy over the last 64d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 9d ago via OSV.dev · verdict-mcp (PyPI)

How Verdict MCP works

What verdict-mcp does

The verdict-mcp MCP server provides structured verification feedback for coding agents working on Python projects. It replaces direct pytest shell-outs with MCP tools that select relevant tests, execute them in an isolated environment, and return compact typed results rather than an entire test-run log.

Its main distinction is failure history. Each failure receives a stable fingerprint based on a normalized failure signature. Volatile values such as memory addresses, temporary paths, identifiers, and durations are removed before hashing, so the same logical problem can be recognized across runs and refactors. Results can indicate whether a failure is pre-existing or associated with the current change.

How it works

The verify tool can inspect the working-tree diff and use a static import graph to choose affected tests. The graph is built with grimp. A full-suite mode is also available through scope="all"; the result includes a selection note when the server falls back from targeted selection.

Checks normally run in an ephemeral container using Podman, with Docker as a fallback. The worktree is mounted read-only at /src and copied to a writable /work directory inside the container. The check run uses --network=none, and the host environment is not changed by the test execution. If no container runtime is available, prefer = "local" can run checks against a temporary copy instead of the worktree in place.

The explain_failure tool retrieves the complete traceback for one check ID only when requested. history reports when a fingerprint was first and last seen and how often it has occurred. This keeps detailed failure output separate from the normal summary.

Setup and configuration

The verdict-mcp MCP server can be started with uvx verdict-mcp, which fetches the package on first use. Permanent alternatives include uv tool install verdict-mcp and pip install verdict-mcp.

An optional verdict.toml file can define the project packages used for impact selection, a container image, a setup command, the local-runtime preference, and the maximum number of reported failures. Package names are guessed when the project list is omitted. A configured setup command may use the network before checks begin; the check run itself is network-disabled. A prebuilt image avoids installing dependencies during setup.

Tools and capabilities

  • verify(scope?, base?): selects and runs affected tests, or runs the requested scope, and returns typed failures with fingerprints and a preexisting flag.
  • explain_failure(check_id): returns the full traceback for a selected failure.
  • history(fingerprint): shows first-seen, last-seen, and occurrence information for a failure fingerprint.
  • run_checks(["ruff", "mypy"]): runs Ruff and mypy and normalizes their results into the verdict schema.

Limitations and notes

Impact selection is intentionally approximate because it relies on static imports. Dynamic imports, fixture lookup by name, and data-driven tests may be missed, so scope="all" is available when broader coverage is needed.

Container setup can still fail before a check starts, including image-pull or credential-helper problems. The README specifically notes that Podman may be affected by a Docker configuration using the gcloud credential helper. Flake detection and coverage-based selection are described as future work rather than current capabilities.

The verdict-mcp MCP server is licensed under Apache-2.0. Its container isolation reduces host-side effects, but the documented setup step can run with network access, so repository configuration should be reviewed before enabling it.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Verdict MCP

verdict-mcp is an MCP server that connects coding agents to sandboxed Python and pytest verification. Its main tools select and run affected tests, retrieve individual failure tracebacks, check fingerprint history, and normalize Ruff or mypy results into compact typed verdicts with pre-existing failure information.

Install it with `uvx verdict-mcp`, `uv tool install verdict-mcp`, or `pip install verdict-mcp`. Configure the MCP client to run the `verdict-mcp` command and set `VERDICT_PROJECT` to the project path.

Yes, verdict-mcp includes a Cursor configuration example using `.cursor/mcp.json`. The configuration runs `uvx` with the `verdict-mcp` argument and passes the project path through `VERDICT_PROJECT`.

It compares stable failure fingerprints across runs and exposes history for each fingerprint. The `history` tool reports first-seen, last-seen, and occurrence information, while `verify` includes a `preexisting` flag.

Yes, checks normally run in an ephemeral Podman container, with Docker as a fallback. The worktree is mounted read-only, the check runs without network access, and `prefer = "local"` provides a temporary-copy fallback when no container runtime is available.

Related MCP servers

All in Code Execution All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewVerdict MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/verdict-mcp?style=directory)](https://allmcps.com/mcp/verdict-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/verdict-mcp"><img src="https://allmcps.com/api/badge/verdict-mcp?style=directory" alt="Verdict MCP on AllMCPs" /></a>