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: mcp-server-codecov

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
• 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. To create an API token:

1. Go to your Codecov instance (e.g., https://codecov.io or your self-hosted URL)
2. Click on your avatar in the top right → Settings
3. Navigate to the "Access" tab
4. Click "Generate Token" and name it (e.g., "MCP Server API Access")
5. Copy the token value and use it in your configuration

Installation

Using npm (Recommended)

The easiest way to use this MCP server is to install it globally via npm:

npm install -g mcp-server-codecov

After installation, the mcp-server-codecov command will be available globally and you can use it directly in your MCP configuration.

Benefits of npm installation:

• ✅ Simple one-command installation
• ✅ Automatic updates with npm update -g mcp-server-codecov
• ✅ No manual build steps required
• ✅ Works across all projects
• ✅ Recommended for production use

From Source (Development Only)

Only use this method if you're contributing to the project or need to modify the source code:

git clone https://github.com/egulatee/mcp-server-codecov.git
cd mcp-server-codecov
npm install
npm run build

Note: For regular usage, prefer the npm installation method above.

Configuration

The server is configured through environment variables:

• CODECOV_BASE_URL (optional): Base URL for the Codecov instance. Defaults to https://codecov.io
• CODECOV_TOKEN (optional): Authentication token for accessing private repositories

Example Configuration for Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Using npm package (recommended):

{
  "mcpServers": {
    "codecov": {
      "command": "npx",
      "args": ["-y", "mcp-server-codecov"],
      "env": {
        "CODECOV_BASE_URL": "https://codecov.io",
        "CODECOV_TOKEN": "your-codecov-token-here"
      }
    }
  }
}

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

Example Configuration for Claude Code

Option 1: Using CLI (Recommended)

Use the Claude Code CLI to add the MCP server with the npm package:

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

This automatically configures the server in your ~/.claude.json file.

cd /path/to/codecov-mcp
npm install && npm run build
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

Option 2: Manual Configuration

Add to your Claude Code MCP settings file at ~/.claude.json:

Using npm package (recommended):

{
  "mcpServers": {
    "codecov": {
      "command": "npx",
      "args": ["-y", "mcp-server-codecov"],
      "env": {
        "CODECOV_BASE_URL": "https://codecov.io",
        "CODECOV_TOKEN": "${CODECOV_TOKEN}"
      }
    }
  }
}

{
  "mcpServers": {
    "codecov": {
      "command": "node",
      "args": ["/absolute/path/to/codecov-mcp/dist/index.js"],
      "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 (e.g., from ~/.zshrc or ~/.bashrc)
• The -y flag for npx automatically accepts the package installation prompt

Self-Hosted Codecov

For self-hosted Codecov instances, simply set the CODECOV_BASE_URL environment variable to your instance URL.

Claude Desktop:

{
  "mcpServers": {
    "codecov": {
      "command": "npx",
      "args": ["-y", "mcp-server-codecov"],
      "env": {
        "CODECOV_BASE_URL": "https://codecov.your-company.com",
        "CODECOV_TOKEN": "your-codecov-token-here"
      }
    }
  }
}

Claude Code CLI:

claude mcp add --transport stdio codecov \
  --env CODECOV_BASE_URL=https://codecov.your-company.com \
  --env CODECOV_TOKEN=${CODECOV_TOKEN} \
  -- npx -y mcp-server-codecov

Claude Code Manual (~/.claude.json):

{
  "mcpServers": {
    "codecov": {
      "command": "npx",
      "args": ["-y", "mcp-server-codecov"],
      "env": {
        "CODECOV_BASE_URL": "https://codecov.your-company.com",
        "CODECOV_TOKEN": "${CODECOV_TOKEN}"
      }
    }
  }
}

Verification and Troubleshooting

Verify npm Installation

After installing via npm, verify the package is correctly installed:

# Check installed version
npm list -g mcp-server-codecov

# Verify command is accessible
which mcp-server-codecov

# Test the package info
npm view mcp-server-codecov version

Verify MCP Server Configuration

After configuring the MCP server, verify it's working correctly:

# List all configured MCP servers
claude mcp list

# Check the codecov server status
claude mcp get codecov

Expected output for npm installation:

codecov: mcp-server-codecov - ✓ Connected

Troubleshooting connection issues:

• If you see "Failed to connect", restart Claude Code or Claude Desktop
• Verify environment variables are set correctly: echo $CODECOV_TOKEN
• Check the configuration: claude mcp get codecov

Common Issues

1. 401 Unauthorized Error

If you get a 401 Unauthorized error when using the tools:

• Check token type: Ensure you're using an API token (from Settings → Access), not an upload token
• Ensure CODECOV_TOKEN is set in the MCP server's env section
• 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

If ${CODECOV_TOKEN} isn't being replaced:

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

4. Connection Failed

If the server shows as not connected:

• Check that the path to dist/index.js is correct and absolute
• Ensure the server is built: npm run build
• Check Claude Code logs for error details

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

Testing

This project maintains 97%+ code coverage with comprehensive unit tests using Vitest.

Running Tests

# Run tests once
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Launch Vitest UI for debugging
npm run test:ui

Coverage Requirements

All code changes must maintain a minimum of 90% coverage across all metrics:

• Statements: ≥90% (currently 97.46%)
• Branches: ≥90% (currently 93.1%)
• Functions: ≥90% (currently 100%)
• Lines: ≥90% (currently 97.46%)

Coverage reports are automatically generated in the coverage/ directory after running npm run test:coverage. Open coverage/index.html in your browser to view detailed coverage information.

Continuous Integration

Tests run automatically on:

• Every push to main and develop branches
• Every pull request targeting main or develop
• Multiple Node.js versions (18.x, 20.x, 22.x)

Coverage reports are uploaded to Codecov, and PR comments show coverage changes for each pull request.

Writing Tests

Tests are located in src/__tests__/ and use Vitest with the following patterns:

• Unit tests: Test individual functions and classes in isolation
• Mocking: Global fetch is mocked to avoid network calls
• MCP SDK mocking: Server components are mocked to prevent actual server startup
• Edge cases: All error paths and edge cases are covered

Example test structure:

import { describe, it, expect } from 'vitest';
import { getConfig, CodecovClient } from '../index.js';

describe('getConfig', () => {
  it('returns default configuration when no env vars set', () => {
    const config = getConfig();
    expect(config.baseUrl).toBe('https://codecov.io');
  });
});

Contributing Guidelines

When contributing:

1. Write tests for all new functionality
2. Ensure all tests pass: npm test
3. Verify coverage meets requirements: npm run test:coverage
4. Tests will run automatically in CI when you open a pull request

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.

Prerequisites

Before creating releases, ensure the repository has the NPM_TOKEN secret configured:

1. Generate an npm access token:

   • Log in to npmjs.com
   • Go to Account Settings → Access Tokens
   • Click "Generate New Token" → Choose "Automation" type
   • Copy the generated token

2. Add the token to GitHub repository secrets:

   • Go to your repository on GitHub
   • Navigate to Settings → Secrets and variables → Actions
   • Click "New repository secret"
   • Name: NPM_TOKEN
   • Value: Paste your npm token
   • Click "Add secret"

Creating a Release

To create a new release:

1. Update version and changelog:

   # Bump version in package.json (major.minor.patch)
   npm version patch  # or 'minor' or 'major'
   
   # Update CHANGELOG.md with release notes
   # Add entry following Keep a Changelog format

2. Commit and push changes:

   git add package.json CHANGELOG.md
   git commit -m "chore: prepare release v1.0.2"
   git push origin main

3. Create and push version tag:

   # Create annotated tag
   git tag -a v1.0.2 -m "Release v1.0.2"
   
   # Push tag to trigger release workflow
   git push origin v1.0.2

4. Automated workflow runs: The GitHub Actions workflow (.github/workflows/release.yml) automatically:

   • Runs all tests to ensure quality
   • Builds the package
   • Publishes to npm with provenance
   • Extracts changelog for this version
   • Creates GitHub release with release notes

5. Verify release:

   • Check GitHub Actions for workflow status
   • Verify package on npm
   • Check GitHub Releases for release notes

Manual Release (Emergency Only)

If the automated workflow fails or for emergency releases:

# Authenticate with npm
npm adduser

# Publish manually
npm publish --access public

# Create GitHub release manually
gh release create v1.0.2 --title "v1.0.2" --notes-file CHANGELOG.md

Version Numbering

This project follows Semantic Versioning:

• Major (v2.0.0): Breaking changes
• Minor (v1.1.0): New features, backward compatible
• Patch (v1.0.1): Bug fixes, backward compatible

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}

Currently supports GitHub repositories (gh). Support for other providers (GitLab, Bitbucket) can be added by modifying the API paths.

License

MIT