Codecov Server

npm version npm downloads codecov Security Policy

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:

1. Go to codecov.io (or your self-hosted URL)
2. Click your avatar → Settings → Access tab
3. Click "Generate Token" and name it "MCP Server API Access"
4. 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:

1. Log in to your Codecov instance (e.g., codecov.io)
2. Navigate to your organization/user account
3. Find the repository you want to activate
4. Click the "Activate" button to enable coverage tracking
5. 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