Provides tools for querying Codecov coverage data, including file-level, commit, repository, and pull request coverage analysis, as well as coverage comparisons between branches, commits, or tags.
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., "@Codecov MCP Server Get coverage for src/index.ts in owner/repo on main"
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.
A Model Context Protocol (MCP) server that provides tools for querying Codecov coverage data. Supports both codecov.io and self-hosted Codecov instances with configurable URL endpoints.
📦 Published on npm: @egulatee/mcp-codecov 🐳 Docker image: ghcr.io/egulatee/mcp-server-codecov
📖 Learn More: Read about building this MCP server with AI in just 2 hours.
Get started in under 2 minutes:
Create an API token (not an upload token) from your Codecov account:
Go to codecov.io (or your self-hosted URL)
Click your avatar → Settings → Access tab
Click "Generate Token" and name it "MCP Server API Access"
Copy the token value
Add to your shell profile (~/.zshrc or ~/.bashrc):
export CODECOV_TOKEN="your-api-token-here"Then reload: source ~/.zshrc
claude mcp add --transport stdio codecov \
--env CODECOV_BASE_URL=https://codecov.io \
--env CODECOV_TOKEN=${CODECOV_TOKEN} \
-- npx -y @egulatee/mcp-codecovclaude mcp get codecovExpected output: codecov: @egulatee/mcp-codecov - ✓ Connected
That's it! You can now use Codecov tools in Claude Code. See Available Tools below.
Related MCP server: simplecov-mcp
File-level coverage: Get detailed line-by-line coverage data for specific files
Commit coverage: Retrieve coverage statistics for individual commits
Repository coverage: Get overall coverage metrics for repositories
Pull request coverage: Analyze coverage changes and impact for pull requests
Coverage comparison: Compare coverage between branches, commits, or tags
Configurable URL: Point to any Codecov instance (codecov.io or self-hosted)
Token authentication: API token support for accessing coverage data
Important: Codecov has two different types of tokens:
Upload Token: Used for pushing coverage reports TO Codecov during CI/CD. Found on your repository's Settings → General page.
API Token: Used for reading coverage data FROM Codecov via the API. Created in your Codecov Settings → Access tab.
This MCP server requires an API token, not an upload token.
Get line-by-line coverage data for a specific file.
Parameters:
owner (required): Repository owner (username or organization)
repo (required): Repository name
file_path (required): Path to the file within the repository (e.g., 'src/index.ts')
ref (optional): Git reference (branch, tag, or commit SHA)
Example:
Get coverage for src/index.ts in owner/repo on main branchGet coverage data for a specific commit.
Parameters:
owner (required): Repository owner
repo (required): Repository name
commit_sha (required): Commit SHA
Example:
Get coverage for commit abc123 in owner/repoGet overall coverage statistics for a repository.
Parameters:
owner (required): Repository owner
repo (required): Repository name
branch (optional): Branch name (defaults to repository's default branch)
Example:
Get overall coverage for owner/repo on main branchGet coverage data for a specific pull request, including coverage changes and file-level impact.
Parameters:
owner (required): Repository owner (username or organization)
repo (required): Repository name
pull_number (required): Pull request number
Example:
Get coverage for pull request #123 in owner/repoUse Cases:
Check if PR meets coverage thresholds before approving
Alert when PR decreases overall coverage
Identify which files in a PR lack coverage
Implement quality gates that block merges if coverage drops
Compare coverage between two git references (branches, commits, or tags).
Parameters:
owner (required): Repository owner (username or organization)
repo (required): Repository name
base (required): Base reference (e.g., 'main', commit SHA)
head (required): Head reference to compare against base
Example:
Compare coverage between main branch and feature-branch in owner/repoUse Cases:
Compare coverage between release branches
Analyze coverage changes between any two commits
Track coverage trends across development cycles
Validate coverage improvements in feature branches
Important Note: Before a repository can receive coverage uploads, it must be activated in Codecov. This is a one-time setup step that cannot be automated via API.
To activate a repository for coverage tracking:
Log in to your Codecov instance (e.g., codecov.io)
Navigate to your organization/user account
Find the repository you want to activate
Click the "Activate" button to enable coverage tracking
Once activated, you can upload coverage reports from your CI/CD pipeline
Why manual activation is required: The Codecov API v2 does not provide a /activate endpoint. Repository activation must be done through the web UI or happens automatically on first coverage upload (depending on your Codecov configuration).
1. 401 Unauthorized Error
Check token type: Ensure you're using an API token (from Settings → Access), not an upload token
Verify the token is valid and has access to the repository
For self-hosted instances, confirm you're using the correct CODECOV_BASE_URL
2. Environment Variable Not Expanding
Make sure the variable is exported in your shell (check ~/.zshrc or ~/.bashrc)
Restart Claude Code after setting environment variables
Verify the variable exists: echo $CODECOV_TOKEN
3. Connection Failed
Restart Claude Code or Claude Desktop
Verify environment variables are set correctly: echo $CODECOV_TOKEN
Check the configuration: claude mcp get codecov
4. HTTP vs HTTPS
Always use https:// for the CODECOV_BASE_URL, not http://:
Correct: https://your-codecov-instance.com
Incorrect: http://your-codecov-instance.com
For self-hosted Codecov instances, use your instance URL:
claude mcp add --transport stdio codecov \
--env CODECOV_BASE_URL=https://codecov.your-company.com \
--env CODECOV_TOKEN=${CODECOV_TOKEN} \
-- npx -y @egulatee/mcp-codecovAdd to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"codecov": {
"command": "npx",
"args": ["-y", "@egulatee/mcp-codecov"],
"env": {
"CODECOV_BASE_URL": "https://codecov.io",
"CODECOV_TOKEN": "your-codecov-token-here"
}
}
}
}Add to ~/.claude.json:
{
"mcpServers": {
"codecov": {
"command": "npx",
"args": ["-y", "@egulatee/mcp-codecov"],
"env": {
"CODECOV_BASE_URL": "https://codecov.io",
"CODECOV_TOKEN": "${CODECOV_TOKEN}"
}
}
}
}Notes:
Environment variable expansion is supported using ${VAR} syntax
Variables like ${CODECOV_TOKEN} will be read from your shell environment
The -y flag for npx automatically accepts the package installation prompt
Pull and run the official multi-platform image from GitHub Container Registry:
docker run --rm -i \
-e CODECOV_TOKEN=your_token \
ghcr.io/egulatee/mcp-server-codecovPlatforms: linux/amd64 and linux/arm64 (Apple Silicon, AWS Graviton)
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"codecov": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CODECOV_TOKEN=your_token",
"ghcr.io/egulatee/mcp-server-codecov"
]
}
}
}With self-hosted Codecov:
docker run --rm -i \
-e CODECOV_TOKEN=your_token \
-e CODECOV_BASE_URL=https://codecov.your-company.com \
ghcr.io/egulatee/mcp-server-codecovAvailable tags: latest, 2, 2.1, 2.1.0 (full semver)
stdio bridge with socat:
The Docker image includes socat, which allows MCP clients that communicate over stdio to connect to the server running inside a container via a TCP socket:
# Start the server exposing a TCP port
docker run --rm -p 3000:3000 \
-e CODECOV_TOKEN=your_token \
ghcr.io/egulatee/mcp-server-codecov
# Bridge stdio ↔ TCP in a second terminal (or from your MCP client config)
socat TCP:localhost:3000 STDIONote:
socatmust also be installed on the host machine running the bridge command. Install withbrew install socat(macOS),apt install socat(Debian/Ubuntu), orapk add socat(Alpine).
npm install -g @egulatee/mcp-codecovBenefits:
Simple one-command installation
Automatic updates with npm update -g @egulatee/mcp-codecov
No manual build steps required
Works across all projects
Verify installation:
npm list -g @egulatee/mcp-codecov
which mcp-codecov
npm view @egulatee/mcp-codecov versionOnly use this method if you're contributing to the project:
git clone https://github.com/egulatee/mcp-server-codecov.git
cd mcp-server-codecov
npm install
npm run buildThen configure with the built path:
Claude Code CLI:
claude mcp add --transport stdio codecov \
--env CODECOV_BASE_URL=https://codecov.io \
--env CODECOV_TOKEN=${CODECOV_TOKEN} \
-- node /absolute/path/to/codecov-mcp/dist/index.jsManual (~/.claude.json):
{
"mcpServers": {
"codecov": {
"command": "node",
"args": ["/absolute/path/to/codecov-mcp/dist/index.js"],
"env": {
"CODECOV_BASE_URL": "https://codecov.io",
"CODECOV_TOKEN": "${CODECOV_TOKEN}"
}
}
}
}Claude Desktop:
{
"mcpServers": {
"codecov": {
"command": "node",
"args": ["/path/to/mcp-server-codecov/dist/index.js"],
"env": {
"CODECOV_BASE_URL": "https://codecov.io",
"CODECOV_TOKEN": "your-codecov-token-here"
}
}
}
}This project maintains 97%+ code coverage with comprehensive unit tests using Vitest.
For detailed testing documentation, including how to run tests, coverage requirements, CI integration, and writing tests, see TESTING.md.
# Install dependencies
npm install
# Build the project
npm run build
# Watch mode for development
npm run watchThis project uses an automated release workflow via GitHub Actions. Releases are published to npm automatically when you push a version tag.
For detailed release instructions, including prerequisites, creating releases, manual releases, and version numbering, see RELEASE.md.
This server uses Codecov's API v2. The API endpoints follow this pattern:
File coverage: /api/v2/gh/{owner}/repos/{repo}/file_report/{file_path}
Commit coverage: /api/v2/gh/{owner}/repos/{repo}/commits/{commit_sha}
Repository coverage: /api/v2/gh/{owner}/repos/{repo}
Pull request coverage: /api/v2/gh/{owner}/repos/{repo}/pulls/{pull_number}
Coverage comparison: /api/v2/gh/{owner}/repos/{repo}/compare/{base}...{head}
Currently supports GitHub repositories (gh). Support for other providers (GitLab, Bitbucket) can be added by modifying the API paths.
📝 Building the Codecov MCP Server in 2 Hours - A detailed walkthrough of developing this server using AI-augmented development techniques
MIT
Compare coverage between two git references (branches, commits, or tags).
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner (username or organization) | |
| repo | Yes | Repository name | |
| base | Yes | Base reference (e.g., 'main', commit SHA) | |
| head | Yes | Head reference to compare against base |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic action of comparing coverage, without explaining any side effects, output format, error behavior, or how coverage is calculated. This is minimal and not transparent enough for an agent to fully anticipate tool behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the core action. It is concise, with no wasted words, and effectively communicates the primary purpose of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, alongside the schema, gives a clear picture of inputs and purpose. However, without an output schema or annotations, the description does not explain what the comparison returns or any additional behavior, leaving the agent with incomplete information about the tool's full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are documented with meaningful descriptions. The tool description adds no additional parameter semantics beyond what the schema already provides. As per the baseline for high schema coverage, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: comparing coverage between two git references. The verb 'compare' and resource 'coverage between two git references' are specific and distinguish it from sibling tools like get_repo_coverage or get_file_coverage, which retrieve individual coverage data rather than compare references.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus the sibling get_* tools. However, the name and description imply a comparative use case, so the usage is inferred but not explicitly stated. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get coverage data for a specific commit, including overall coverage percentage and file-level changes.
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner (username or organization) | |
| repo | Yes | Repository name | |
| commit_sha | Yes | Commit SHA to get coverage for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of disclosing behavior. It only mentions the type of data returned (coverage percentage and file-level changes) but does not disclose read-only nature, authentication needs, rate limits, or side effects. The term 'file-level changes' is ambiguous—unclear if it means file modifications or file-specific coverage metrics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's purpose. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description must explain return values. It vaguely mentions 'overall coverage percentage and file-level changes,' but does not specify the response structure, data types, or whether it returns a single object or array. This is sufficient for a simple get tool but leaves gaps for an agent to predict the exact output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (owner, repo, commit_sha) are already documented. The description adds no additional parameter-level meaning beyond what the schema provides, earning the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get coverage data for a specific commit' with a specific verb and resource. It also distinguishes itself from siblings like get_repo_coverage and get_file_coverage by focusing on a specific commit and mentioning 'overall coverage percentage and file-level changes.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by the phrase 'for a specific commit,' suggesting it is for commit-level queries, but there is no explicit guidance on when to use this versus siblings like get_repo_coverage or compare_coverage. No exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get line-by-line coverage data for a specific file in a repository. Returns coverage percentages and line-level hit/miss information.
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner (username or organization) | |
| repo | Yes | Repository name | |
| file_path | Yes | Path to the file within the repository (e.g., 'src/index.ts') | |
| ref | No | Git reference (branch, tag, or commit SHA). Defaults to default branch if not specified. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states what it returns (coverage percentages and line-level hit/miss info) but does not disclose any behavioral traits such as authentication requirements, rate limits, error behavior, or whether the operation is read-only. Although 'Get' implies read-only, no explicit safety or side-effect disclosure is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that clearly states the purpose and return value with zero wasted words. It is appropriately concise for the simplicity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and return value, and the schema handles parameter details. However, with no output schema and no annotations, the description does not fully contextualize the tool's usage among siblings or explain edge-case behaviors. It is sufficient for basic invocation but lacks guidance on when to choose it over alternatives.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all four parameters documented in the input schema. The description adds no additional parameter-level meaning beyond what the schema provides. It simply restates that the tool works on a 'specific file', which is already clear from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets line-by-line coverage data for a specific file in a repository, with return details (percentages and hit/miss info). It distinguishes itself from sibling tools like get_commit_coverage, get_repo_coverage, get_pull_request_coverage, and compare_coverage by focusing on file-level data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus the sibling tools. It does not mention alternatives, exclusions, or preferred scenarios. A user/agent must infer from the name and description that this is for file-level coverage, but no comparative context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get coverage data for a specific pull request, including coverage changes and file-level impact.
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner (username or organization) | |
| repo | Yes | Repository name | |
| pull_number | Yes | Pull request number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. It offers only a high-level summary without mentioning authentication requirements, rate limits, response format, or any side effects. The 'Get' verb implies read-only, but this is not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant information. Every word earns its place, and it conveys the tool's purpose and scope efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives the essence of the tool's output (coverage changes and file-level impact) but does not explain the return value structure or any limitations. For a tool with no output schema and no annotations, slightly more detail on the expected data format would improve completeness, but the simple 3-parameter scope keeps it adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for all three parameters (owner, repo, pull_number), and their descriptions are self-explanatory. The tool description adds no additional meaning to the parameters, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Get') and resource ('coverage data for a specific pull request'), and also specifies the output scope ('coverage changes and file-level impact'). This distinguishes it from sibling tools that target files, commits, repos, or comparisons.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for pull request coverage data, but does not explicitly state when to prefer this over siblings like get_file_coverage or compare_coverage. It lacks direct 'when-to-use' or 'when-not-to-use' guidance, making the usage context only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get overall coverage statistics for a repository, optionally for a specific branch.
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner (username or organization) | |
| repo | Yes | Repository name | |
| branch | No | Branch name (defaults to repository's default branch) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It clearly signals a read-only operation ('Get') and notes the branch optionality. However, it does not disclose return format, what statistics are included, or any rate limits. Minimal extra context beyond obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the verb 'Get', and contains no filler. 'Overall coverage statistics' adds precision without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description could be more detailed about the returned statistics. However, for a simple repo-level coverage tool, the description sufficiently captures the core function and scope. It lacks metrics details but is not misleading.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 3 parameters with descriptions (100% coverage), so baseline 3. The description adds no additional parameter semantics; it merely repeats the optionality of the branch parameter already documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Get' and resource 'repository' with explicit scope 'overall coverage statistics'. It clearly distinguishes from sibling tools like get_file_coverage and get_commit_coverage, which target different granularities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied but not explicit. The description indicates repo-level coverage and optional branch filtering, but it does not mention alternative tools or state when not to use this tool. Sibling names help, but the description itself lacks direct comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.4.0compare_coverageget_commit_coverageget_file_coverageget_pull_request_coverageget_repo_coverageScored across 5 tools
Each tool targets a distinct coverage aspect: repo, commit, file, pull request, or comparison between references. No functional overlap.
All tools follow a clear verb_noun pattern (get_<entity>_coverage, compare_coverage), with no mixing of styles.
Five tools cover the essential coverage operations for a code coverage server, neither too few nor excessive.
Covers repo, commit, file, PR, and comparison coverage queries. Minor gap: no tool for listing commits or historical trends, but core use cases are well supported.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Query your OpsLevel internal developer portal: catalog, maturity data, and tech docs.
Query Honeycomb observability data: traces, events, metrics, SLOs, triggers, and boards.
Access the GitHub API, enabling file operations, repository management, search functionality, and…
