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.