# MCP Server for Codecov

[![npm version](https://img.shields.io/npm/v/@egulatee/mcp-codecov.svg)](https://www.npmjs.com/package/@egulatee/mcp-codecov)
[![npm downloads](https://img.shields.io/npm/dm/@egulatee/mcp-codecov.svg)](https://www.npmjs.com/package/@egulatee/mcp-codecov)
[![codecov](https://codecov.io/gh/egulatee/mcp-server-codecov/branch/main/graph/badge.svg)](https://codecov.io/gh/egulatee/mcp-server-codecov)
![Test and Coverage](https://github.com/egulatee/mcp-server-codecov/workflows/Test%20and%20Coverage/badge.svg)
[![Security Policy](https://img.shields.io/badge/Security-Policy-blue.svg)](https://github.com/egulatee/mcp-server-codecov/security/policy)
![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)
![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg)
![MCP](https://img.shields.io/badge/MCP-Server-orange.svg)

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](https://www.npmjs.com/package/@egulatee/mcp-codecov)
🐳 **Docker image:** [ghcr.io/egulatee/mcp-server-codecov](https://github.com/egulatee/mcp-server-codecov/pkgs/container/mcp-server-codecov)

> **📖 Learn More**: Read about [building this MCP server with AI in just 2 hours](https://blog.aiaugmentedsoftwaredevelopment.com/posts/building-codecov-mcp-server-in-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](https://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`):

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

Then reload: `source ~/.zshrc`

### 3. Install the MCP server

```bash
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

```bash
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](#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](https://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:

```bash
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`

```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`:

```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:

```bash
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):

```json
{
  "mcpServers": {
    "codecov": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CODECOV_TOKEN=your_token",
        "ghcr.io/egulatee/mcp-server-codecov"
      ]
    }
  }
}
```

**With self-hosted Codecov:**

```bash
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`](https://linux.die.net/man/1/socat), which allows MCP clients that communicate over stdio to connect to the server running inside a container via a TCP socket:

```bash
# 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

```bash
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:**
```bash
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:

```bash
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:**
```bash
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`):**
```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:**
```json
{
  "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](TESTING.md)**.

## Development

```bash
# 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](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](https://blog.aiaugmentedsoftwaredevelopment.com/posts/building-codecov-mcp-server-in-2-hours/) - A detailed walkthrough of developing this server using AI-augmented development techniques

## License

MIT