How do I use simplecov-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@simplecov-mcp Show me the uncovered lines in app/models/user.rb" 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.

simplecov-mcp

An MCP server that lets Claude directly access SimpleCov coverage reports.

No need to read the entire coverage/.resultset.json (which can be tens of MB). Retrieve only the data you need via tools.

Setup

git clone https://github.com/yourname/simplecov-mcp.git
cd simplecov-mcp
pnpm install && pnpm build

Then, in your Rails project root, register the MCP server:

claude mcp add simplecov node /path/to/simplecov-mcp/build/index.js

This adds the MCP server to your project's .mcp.json. The server automatically detects the coverage/ directory from the working directory.

To specify the coverage path explicitly:

claude mcp add simplecov -e SIMPLECOV_COVERAGE_PATH=/path/to/coverage node /path/to/simplecov-mcp/build/index.js

After adding, restart Claude Code and verify with /mcp.

Tools

`get_summary`

Returns the overall coverage summary.

> get_summary

{
  "lastRun": { "line": 100, "branch": 100 },
  "totalFiles": 1669,
  "computed": { "lineCoverage": 53.56, "branchCoverage": 48.07 }
}

`list_files`

Lists files with their coverage rates. Supports sorting and filtering.

Parameter	Type	Default	Description
`sort_by`	`path` \| `line_coverage` \| `branch_coverage` \| `missed_lines`	`path`	Sort key
`order`	`asc` \| `desc`	`asc`	Sort order
`min_coverage`	number	-	Minimum coverage percentage
`max_coverage`	number	-	Maximum coverage percentage
`path_pattern`	string	-	Partial match filter for file paths

> list_files sort_by=missed_lines order=desc max_coverage=50

[
  { "file": ".../inquiries_controller.rb", "line": "8.96% (37/413)", "missed": 376 },
  ...
]

`get_file_coverage`

Returns detailed coverage for a specific file, including per-line hit counts, uncovered line numbers, and branch coverage.

Parameter	Type	Description
`file_path`	string (required)	File path. Matched by suffix

> get_file_coverage file_path=app/models/user.rb

{
  "filePath": "/usr/src/app/app/models/user.rb",
  "lineCoverage": "85.71% (12/14)",
  "uncoveredLineNumbers": [42, 43],
  "lines": [...],
  "branches": [...]
}

`get_uncovered_lines`

Extracts only uncovered lines and branches. Useful when adding tests.

> get_uncovered_lines file_path=app/services/order_service.rb

{
  "filePath": "/usr/src/app/app/services/order_service.rb",
  "lineCoverage": "72.5%",
  "uncoveredLineNumbers": [15, 16, 42, 43, 44],
  "uncoveredBranches": [
    { "condition": "[:if, 3, 15, 6, 15, 40]", "branch": "[:else, 5, 15, 6, 15, 40]" }
  ]
}

Usage Examples with Claude

"Show me files with low coverage"
"Show uncovered lines in app/models/user.rb"
"List controllers with coverage below 50%"
"Write tests for the uncovered lines in this file"

How It Works

Rails Project
├── coverage/
│   ├── .resultset.json  ← Generated by SimpleCov (tens of MB)
│   └── .last_run.json   ← Summary
└── .mcp.json            ← MCP configuration (created by claude mcp add)

simplecov-mcp searches for the coverage/ directory starting from cwd,
then walking up to parent directories. It parses .resultset.json and
holds the data in memory. Claude retrieves only the needed portions
via tools.