# MCP Test Runner

> MCP Test Runner is an open-source MCP server for developer tools. MCP server that runs pytest and Jest locally and reports normalized test results. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, Linux, macOS
- **Repository:** https://github.com/lovranran/mcp-test-runner
- **MCP Registry name:** io.github.LovRanRan/mcp-test-runner
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-18

## About

The README says this server runs pytest and Jest inside a bounded working directory and returns the raw command output, so an AI client can check claims against real test execution instead of guessing. It also includes a parser that turns pytest and Jest JSON output into one common result format, plus a pytest-cov summary of coverage totals.

Execution is handled by subprocess calls with timeouts and POSIX CPU and memory caps rather than Docker, and the server itself does not use an LLM. Single pytest node ids and Jest test-name patterns can be targeted individually. Coverage summaries are pytest-only in this version.

The project is described as the verification layer in a three-server stack for the wayfinder codebase onboarding agent, alongside repository mapping and Python AST lookup servers. It suits developers wiring test evidence into agent workflows.

## Features

- **Pytest execution:** Runs pytest in a bounded working directory with optional test filtering and resource limits.
- **Jest execution:** Runs Jest through npx with JSON output written to a file.
- **Single test targeting:** Runs one pytest node id or one Jest test-name pattern.
- **Normalized result parsing:** Converts pytest and Jest JSON output into one shared result schema.
- **Coverage totals:** Returns pytest-cov coverage totals from a JSON coverage report.
- **Resource-capped subprocesses:** Applies timeouts and POSIX CPU and memory limits to test runs.

## Good for

- Verifying an AI agent's claims about code behaviour by running the relevant tests
- Running a single failing pytest or Jest test from an agent workflow
- Collecting pytest coverage totals during codebase onboarding
- Normalizing raw Jest or pytest JSON output for downstream tooling

## Install

### Claude Code (Terminal)

```sh
claude mcp add mcp-test-runner -- uvx lovranran-mcp-test-runner
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "mcp-test-runner": {
      "command": "uvx",
      "args": [
        "lovranran-mcp-test-runner"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "mcp-test-runner": {
      "command": "uvx",
      "args": [
        "lovranran-mcp-test-runner"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "mcp-test-runner": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "lovranran-mcp-test-runner"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "mcp-test-runner": {
      "command": "uvx",
      "args": [
        "lovranran-mcp-test-runner"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "mcp-test-runner": {
      "command": "uvx",
      "args": [
        "lovranran-mcp-test-runner"
      ]
    }
  }
}
```

## Tools

- `health`: Returns ok for smoke checks.
- `run_pytest`: Run pytest in a bounded working directory and return raw command output.
- `run_jest`: Run Jest through npx jest and return raw command output.
- `run_single_test`: Run one pytest node id or one Jest test-name pattern.
- `parse_test_output`: Normalize test runner JSON output.
- `get_coverage_summary`: Return pytest-cov JSON coverage totals.

## FAQ

### Does the server use an LLM?

No. The README says test results come from subprocess execution and structured parser output.

### Is coverage reporting available for Jest?

No. The README says the coverage summary is pytest-only in v1.

### Does it run in Docker?

No. The README says v1 does not use Docker and relies on cwd validation, subprocess timeouts, and POSIX resource limits.

### What Python version is required?

The README lists Python 3.11+ as the supported scope.

### Is MCP Test Runner free?

Yes. MCP Test Runner is open source, so you can use and self-host it for free.

### How do I add MCP Test Runner to Claude Code?

Run this command in your terminal: claude mcp add mcp-test-runner -- uvx lovranran-mcp-test-runner

### What are the best alternatives to MCP Test Runner?

The closest alternatives to MCP Test Runner are Test, Testing, Api Testing MCP, Test Inventory and Api Test MCP.

## Where this comes from

- Description: written from the project's README and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [Test](https://ai-powered.com/mcp/test-2): Test is an open-source MCP server for developer tools.
- [Testing](https://ai-powered.com/mcp/testing): Testing is an open-source MCP server for developer tools.
- [Api Testing MCP](https://ai-powered.com/mcp/api-testing-mcp): Api Testing MCP is an open-source MCP server for developer tools.
- [Test Inventory](https://ai-powered.com/mcp/test-inventory): Test Inventory is an open-source MCP server for e-commerce.
- [Api Test MCP](https://ai-powered.com/mcp/api-test-mcp): Api Test MCP is an open-source MCP server for developer tools.
- [Pare Test](https://ai-powered.com/mcp/pare-test): Pare Test is an open-source MCP server for developer tools.
- [Test Coverage MCP](https://ai-powered.com/mcp/test-coverage-mcp): Test Coverage MCP is an open-source MCP server for developer tools.
- [MCP Server](https://ai-powered.com/mcp/mcp-server-mweo0sk4): MCP Server is an MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/mcp-test-runner
