codecov-mcp

The most comprehensive Codecov MCP server — 35+ tools covering the Codecov REST API v2, plus 5 prompts and 4 resources.

Built for Claude Code and any MCP-compatible AI agent.

Why?

Instead of switching to the Codecov web UI, your AI assistant can directly:

Review PR coverage — patch %, impacted files, and line-level diffs in one call
Find coverage gaps — drill from repo → directory → file → uncovered lines
Track trends — see if coverage is improving or declining over time
Debug CI — inspect uploads, flags, and components
Find flaky tests — identify tests failing on your default branch
Validate config — check codecov.yaml before committing

Quick Start

1. Get a Codecov API Token

Go to Codecov Settings > Access and generate an API Access Token (not an upload token).

2. Add codecov-mcp to Your MCP Client

Pick your tool below for platform-specific setup instructions.

Claude Code

CLI install (macOS / Linux):

claude mcp add --transport stdio codecov --env CODECOV_TOKEN=your-token-here -- npx -y codecov-mcp

CLI install (Windows):

claude mcp add codecov --env CODECOV_TOKEN=your-token-here -- cmd /c npx -y codecov-mcp

Project-scoped (Windows):

claude mcp add --scope project codecov --env CODECOV_TOKEN=your-token-here -- cmd /c npx -y codecov-mcp

On macOS/Linux, add --scope project after add in the first command.

JSON fallback — if the CLI doesn't work in your environment, add to .claude.json (project) or ~/.claude.json (user):

macOS / Linux:

{
  "mcpServers": {
    "codecov": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codecov-mcp"],
      "env": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "codecov": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "codecov-mcp"],
      "env": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}

Codex

CLI install (all platforms):
codex mcp add codecov --env CODECOV_TOKEN=your-token-here -- npx -y codecov-mcp
Config is stored in ~/.codex/config.toml (user) or .codex/config.toml (project). The same config is shared with the Codex IDE extension.

Gemini CLI / Gemini Code Assist

JSON config (all platforms) — add to .gemini/settings.json (project) or ~/.gemini/settings.json (user):
{
  "mcpServers": {
    "codecov": {
      "command": "npx",
      "args": ["-y", "codecov-mcp"],
      "env": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}
Windows: If you get spawn npx ENOENT, change "command" to "cmd" and "args" to ["/c", "npx", "-y", "codecov-mcp"].

Gemini Code Assist agent mode in VS Code is powered by Gemini CLI and uses the same config.

VS Code (GitHub Copilot)

VS Code uses "servers" (not "mcpServers").

JSON config (all platforms) — create .vscode/mcp.json in your project root:
{
  "servers": {
    "codecov": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codecov-mcp"],
      "env": {
        "CODECOV_TOKEN": "${input:codecov-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "codecov-token",
      "type": "promptString",
      "description": "Codecov API Token",
      "password": true
    }
  ]
}
Windows: If you get spawn npx ENOENT, change "command" to "cmd" and "args" to ["/c", "npx", "-y", "codecov-mcp"].

You can also use MCP: Open User Configuration from the command palette for user-level config.

Cursor

JSON config (all platforms) — create .cursor/mcp.json (project) or ~/.cursor/mcp.json (user):
{
  "mcpServers": {
    "codecov": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codecov-mcp"],
      "env": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}
Windows: If you get spawn npx ENOENT, change "command" to "cmd" and "args" to ["/c", "npx", "-y", "codecov-mcp"].

Windsurf

JSON config (all platforms) — edit ~/.codeium/windsurf/mcp_config.json, or add via Windsurf Settings > Cascade > MCP Servers:
{
  "mcpServers": {
    "codecov": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codecov-mcp"],
      "env": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}
Windows: If you get spawn npx ENOENT, change "command" to "cmd" and "args" to ["/c", "npx", "-y", "codecov-mcp"].

Additional Tools

Kilo Code

Open Kilo Code Settings > Agent Behaviour > MCP Servers, then use Edit Global MCP or Edit Project MCP.

Project config — .kilocode/mcp.json

macOS / Linux:

{
  "mcpServers": {
    "codecov": {
      "command": "npx",
      "args": ["-y", "codecov-mcp"],
      "env": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "codecov": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "codecov-mcp"],
      "env": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}

Kilo CLI

JSON config — add to kilo.json or .kilo/kilo.json:

macOS / Linux:

{
  "mcp": {
    "codecov": {
      "type": "local",
      "command": ["npx", "-y", "codecov-mcp"],
      "enabled": true,
      "environment": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}

Windows:

{
  "mcp": {
    "codecov": {
      "type": "local",
      "command": ["cmd", "/c", "npx", "-y", "codecov-mcp"],
      "enabled": true,
      "environment": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}

Roo Code

Open the Roo Code pane, click the MCP Servers icon, then use Edit Global MCP or Edit Project MCP.

Project config — .roo/mcp.json

macOS / Linux:

{
  "mcpServers": {
    "codecov": {
      "command": "npx",
      "args": ["-y", "codecov-mcp"],
      "env": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "codecov": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "codecov-mcp"],
      "env": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}

Warp

Open Settings > MCP Servers in Warp, click + Add, and paste:
{
  "mcpServers": {
    "codecov": {
      "command": "npx",
      "args": ["-y", "codecov-mcp"],
      "env": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}
Also accessible from Warp Drive > Personal > MCP Servers or the Command Palette (Open MCP Servers).

Windows: If npx cannot be resolved, use "command": "cmd" and "args": ["/c", "npx", "-y", "codecov-mcp"].

OpenCode

JSON config — add to opencode.json:

macOS / Linux:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codecov": {
      "type": "local",
      "command": ["npx", "-y", "codecov-mcp"],
      "enabled": true,
      "environment": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}

Windows:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codecov": {
      "type": "local",
      "command": ["cmd", "/c", "npx", "-y", "codecov-mcp"],
      "enabled": true,
      "environment": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}

Droid CLI

CLI install:

droid mcp add codecov "npx -y codecov-mcp" --env CODECOV_TOKEN=your-token-here

Or add to .factory/mcp.json:

{
  "mcpServers": {
    "codecov": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codecov-mcp"],
      "env": {
        "CODECOV_TOKEN": "your-token-here"
      },
      "disabled": false
    }
  }
}

Windows: If npx cannot be resolved, use "command": "cmd" and "args": ["/c", "npx", "-y", "codecov-mcp"].

Cline

Open the Cline sidebar > MCP Servers icon > Configure MCP Servers, then add:
{
  "mcpServers": {
    "codecov": {
      "command": "npx",
      "args": ["-y", "codecov-mcp"],
      "env": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}
Windows: Use "command": "cmd" and "args": ["/c", "npx", "-y", "codecov-mcp"].

Continue

Add to .continue/config.yaml or via the Continue settings UI:

mcpServers:
  - name: codecov
    command: npx
    args:
      - -y
      - codecov-mcp
    env:
      CODECOV_TOKEN: your-token-here

Zed

Add to Zed settings (settings.json via Zed > Settings or File > Settings):

{
  "context_servers": {
    "codecov": {
      "command": {
        "path": "npx",
        "args": ["-y", "codecov-mcp"],
        "env": {
          "CODECOV_TOKEN": "your-token-here"
        }
      }
    }
  }
}

Claude Desktop

Open Claude Desktop > Settings > Developer > Edit Config, then add:

macOS / Linux:

{
  "mcpServers": {
    "codecov": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codecov-mcp"],
      "env": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "codecov": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "codecov-mcp"],
      "env": {
        "CODECOV_TOKEN": "your-token-here"
      }
    }
  }
}

Restart Claude Desktop after saving.

If you're in a git repo with a public GitHub/GitLab/Bitbucket remote, the server auto-detects your service, owner, and repo. Enterprise/self-hosted users should set CODECOV_SERVICE, CODECOV_OWNER, and CODECOV_REPO explicitly.

3. Start Using It

Ask your AI agent things like:

"What's the current coverage for this repo?"

"Show me the coverage impact of PR #42"

"Which files have the worst coverage?"

"What lines in src/auth.ts aren't covered by tests?"

"Are there any flaky tests?"

Tools (37 total, 35 default + 2 admin opt-in)

Coverage

Tool	Description
`get_coverage_totals`	Coverage summary for a commit — totals only by default for efficiency. Set `include_files=true` for per-file data.
`get_coverage_trend`	Time-series coverage data with min/max/avg per interval
`get_coverage_report`	Full report with per-file coverage and line-level detail
`get_coverage_tree`	Hierarchical coverage by directory — great for finding low-coverage areas
`get_file_coverage`	Line-by-line coverage for a file, with computed `uncoveredLines` array

Comparison (all accept `pullid` for PR comparison)

Tool	Description
`compare_coverage`	Compare two commits or a PR — base/head/diff totals and per-file changes
`compare_impacted_files`	Only files with changed coverage — efficient for large PRs
`compare_file`	Line-level coverage diff for a single file
`compare_flags`	Compare by flag (unit, integration, e2e)
`compare_components`	Compare by component (frontend, backend)
`compare_segments`	Chunk-level diffs — most granular view available

Pull Requests

Tool	Description
`list_pulls`	PRs with coverage impact, filterable by state
`get_pull`	Base/head/patch coverage percentages for a PR

Repository & Branches

Tool	Description
`list_repos`	All repos for an owner, filterable and sortable
`get_repo`	Repo details and current coverage
`get_repo_config`	Active Codecov YAML config
`list_branches`	Branches with coverage data
`get_branch`	Coverage for a specific branch

Commits

Tool	Description
`list_commits`	Commits with coverage totals
`get_commit`	Detailed coverage for a commit
`list_commit_uploads`	Upload sessions — useful for debugging CI

Flags & Components

Tool	Description
`list_flags`	Coverage flags and percentages
`get_flag_coverage_trend`	Time-series for a specific flag
`list_components`	Coverage components defined in codecov.yaml

Owners & Users

Tool	Description
`list_owners`	Organizations/users accessible to the token
`get_owner`	Owner details
`list_users`	Users in an org with activation status
`get_user`	User details

Admin Tools (opt-in)

These tools are disabled by default for safety. Set CODECOV_ENABLE_ADMIN_TOOLS=true to enable them.

Tool	Description
`update_user`	Activate/deactivate a user (requires `confirm: true`)
`list_user_sessions`	Login sessions with tokens and timestamps

Test Analytics & Evaluations

Tool	Description
`list_test_analytics`	Test results with pass/fail/duration analytics
`get_eval_summary`	AI/LLM evaluation metrics
`get_eval_comparison`	Compare eval metrics between commits

Composite (High-Value Multi-Call Tools)

Tool	Description
`get_coverage_summary`	Start here. Full situational awareness in one call — repo coverage, trend direction, flag breakdown, and open PR count.
`get_pr_coverage`	Best for code review. Combines PR details (patch/base/head coverage) with impacted files in one call.
`find_flaky_tests`	Tests failing on default branch — strong flaky test candidates
`validate_yaml`	Validate `codecov.yaml` before committing (no auth required)

Prompts (5)

MCP prompts are reusable workflows your AI agent can execute:

Prompt	Description
`coverage_review`	Analyze coverage gaps and suggest improvements
`pr_coverage_check`	Review a PR's coverage impact end-to-end
`suggest_tests`	Suggest test cases for uncovered lines in a file
`flaky_test_report`	Report on flaky tests that need attention
`coverage_health_check`	Full repo health report card with grade and action items

Resources (4)

MCP resources provide data your agent can read directly:

URI	Description
`codecov://{owner}/repos`	All repos for an owner
`codecov://repo/{owner}/{repo}`	Repo coverage summary
`codecov://repo/{owner}/{repo}/flags`	Flag coverage
`codecov://repo/{owner}/{repo}/components`	Component coverage

Configuration

All configuration is via environment variables:

Variable	Required	Default	Description
`CODECOV_TOKEN`	Yes*	—	Codecov API access token
`CODECOV_API_BASE_URL`	No	`https://api.codecov.io`	API base URL (for self-hosted)
`CODECOV_SERVICE`	No	auto-detected	`github`, `gitlab`, `bitbucket`, etc.
`CODECOV_OWNER`	No	auto-detected	Organization or username
`CODECOV_REPO`	No	auto-detected	Repository name
`CODECOV_TIMEOUT_MS`	No	`30000`	Request timeout in ms
`CODECOV_MAX_RETRIES`	No	`3`	Max retries on 429/5xx
`CODECOV_CACHE_TTL_MS`	No	`300000`	Cache TTL in ms (5 min)
`CODECOV_ENABLE_ADMIN_TOOLS`	No	`false`	Enable `update_user` and `list_user_sessions`

* Not required for validate_yaml which uses a public endpoint.

Parameter Resolution Order

For service, owner, and repo, the server resolves values in this order:

Tool argument — passed directly in the tool call
Environment variable — CODECOV_SERVICE, CODECOV_OWNER, CODECOV_REPO
Git remote — auto-detected from git remote get-url origin
Error — clear message explaining what to set

Supported Services

Service	Value
GitHub.com	`github`
GitLab.com	`gitlab`
Bitbucket Cloud	`bitbucket`
GitHub Enterprise	`github_enterprise`
GitLab Self-Managed	`gitlab_enterprise`
Bitbucket Data Center	`bitbucket_server`

Troubleshooting

Error	Fix
`CODECOV_TOKEN is not set`	Use an API Access Token (not upload token) from Codecov Settings
`Could not determine git service`	Run from a git repo with a recognized remote, or set `CODECOV_SERVICE`/`CODECOV_OWNER`/`CODECOV_REPO`
`Authentication failed (401)`	Token is invalid or expired — generate a new one
`Resource not found (404)`	Check owner/repo names and that the repo has coverage data
Windows: `spawn npx ENOENT`	Use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "codecov-mcp"]`, or try `"command": "npx.cmd"`
Stale data	Set `CODECOV_CACHE_TTL_MS=0` to disable caching

More troubleshooting: Installation Guide — Troubleshooting

Development

git clone https://github.com/ScottN-PV/codecov-mcp.git
cd codecov-mcp
npm install
npm run build
npm test

Scripts

Command	Description
`npm run build`	Compile TypeScript to `dist/`
`npm test`	Run unit tests
`npm run test:coverage`	Run tests with coverage report
`npm run lint`	Lint with ESLint

Project Structure

src/
├── index.ts          # Entry point (stdio transport)
├── server.ts         # MCP server setup — registers all tools/prompts/resources
├── client.ts         # Codecov API client with retry and caching
├── config.ts         # Environment variable configuration
├── cache.ts          # LRU cache with TTL
├── types.ts          # TypeScript type definitions
├── schemas/
│   └── shared.ts     # Shared Zod schemas (service, pagination, etc.)
├── tools/            # Tool implementations (one file per API group)
│   ├── coverage.ts   # get_coverage_totals, get_coverage_tree, etc.
│   ├── comparison.ts # compare_coverage, compare_impacted_files, etc.
│   ├── composite.ts  # get_coverage_summary, get_pr_coverage, etc.
│   └── ...           # owners, users, repos, branches, commits, pulls, flags, components, test-analytics, evaluations
├── prompts/          # MCP prompt definitions
├── resources/        # MCP resource definitions
└── utils/            # Error handling, formatting, git remote parsing

License

MIT — see LICENSE for details.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
src		src
tests		tests
.gitignore		.gitignore
.npmrc		.npmrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
STATUS.md		STATUS.md
codecov.yml		codecov.yml
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
sonar-project.properties		sonar-project.properties
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository navigation

About

Repository files navigation

codecov-mcp

Why?

Quick Start

1. Get a Codecov API Token

2. Add codecov-mcp to Your MCP Client

3. Start Using It

Tools (37 total, 35 default + 2 admin opt-in)

Coverage

Comparison (all accept `pullid` for PR comparison)

Pull Requests

Repository & Branches

Commits

Flags & Components

Owners & Users

Admin Tools (opt-in)

Test Analytics & Evaluations

Composite (High-Value Multi-Call Tools)

Prompts (5)

Resources (4)

Configuration

Parameter Resolution Order

Supported Services

Troubleshooting

Development

Scripts

Project Structure

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

codecov-mcp

Why?

Quick Start

1. Get a Codecov API Token

2. Add codecov-mcp to Your MCP Client

3. Start Using It

Tools (37 total, 35 default + 2 admin opt-in)

Coverage

Comparison (all accept pullid for PR comparison)

Pull Requests

Repository & Branches

Commits

Flags & Components

Owners & Users

Admin Tools (opt-in)

Test Analytics & Evaluations

Composite (High-Value Multi-Call Tools)

Prompts (5)

Resources (4)

Configuration

Parameter Resolution Order

Supported Services

Troubleshooting

Development

Scripts

Project Structure

License

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Comparison (all accept `pullid` for PR comparison)