MCP Server for Codecov

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.

Quick Start (Claude Code)

Get started in under 2 minutes:

1. Get your Codecov API token

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

2. Set your environment variable

Add to your shell profile (~/.zshrc or ~/.bashrc):

export CODECOV_TOKEN="your-api-token-here"

Then reload: source ~/.zshrc

3. Install the MCP server

claude mcp add --transport stdio codecov \
  --env CODECOV_BASE_URL=https://codecov.io \
  --env CODECOV_TOKEN=${CODECOV_TOKEN} \
  -- npx -y @egulatee/mcp-codecov

4. Verify installation

claude mcp get codecov

Expected output: codecov: @egulatee/mcp-codecov - ✓ Connected

That's it! You can now use Codecov tools in Claude Code. See Available Tools below.

Features

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

Token Types

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.

Available Tools

get_file_coverage

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 branch

get_commit_coverage

Get 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/repo

get_repo_coverage

Get 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 branch

get_pull_request_coverage

Get 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/repo

Use 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

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/repo

Use 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

Repository Activation

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.

Manual Activation Process

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).

Verification and Troubleshooting

Common Issues

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

Advanced Configuration

Self-Hosted Codecov

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-codecov

Claude Desktop Setup

Add 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"
      }
    }
  }
}

Manual Configuration (Claude Code)

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

Docker (no Node.js required)

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-codecov

Platforms: 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-codecov

Available 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 STDIO

Note: socat must also be installed on the host machine running the bridge command. Install with brew install socat (macOS), apt install socat (Debian/Ubuntu), or apk add socat (Alpine).

Installing from npm Globally

npm install -g @egulatee/mcp-codecov

Benefits:

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 version

Development Installation (Source)

Only 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 build

Then 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.js

Manual (~/.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"
      }
    }
  }
}

Testing

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.

Development

# Install dependencies
npm install

# Build the project
npm run build

# Watch mode for development
npm run watch

Release Process

This 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.

API Compatibility

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.

Resources

📝 Building the Codecov MCP Server in 2 Hours - A detailed walkthrough of developing this server using AI-augmented development techniques

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 128 Commits
.github		.github
docs		docs
scripts		scripts
src		src
test		test
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.nvmrc		.nvmrc
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
PUBLISHING.md		PUBLISHING.md
README.md		README.md
RELEASE.md		RELEASE.md
SECURITY.md		SECURITY.md
TESTING.md		TESTING.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
codecov.yml		codecov.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

MCP Server for Codecov

Quick Start (Claude Code)

1. Get your Codecov API token

2. Set your environment variable

3. Install the MCP server

4. Verify installation

Features

Token Types

Available Tools

get_file_coverage

get_commit_coverage

get_repo_coverage

get_pull_request_coverage

compare_coverage

Repository Activation

Manual Activation Process

Verification and Troubleshooting

Common Issues

Advanced Configuration

Self-Hosted Codecov

Claude Desktop Setup

Manual Configuration (Claude Code)

Docker (no Node.js required)

Installing from npm Globally

Development Installation (Source)

Testing

Development

Release Process

API Compatibility

Resources

License

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 17

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages