{
  "markdown": "# MCP Server for Codecov\n\n[![npm version](https://img.shields.io/npm/v/@egulatee/mcp-codecov.svg)](https://www.npmjs.com/package/@egulatee/mcp-codecov)\n[![npm downloads](https://img.shields.io/npm/dm/@egulatee/mcp-codecov.svg)](https://www.npmjs.com/package/@egulatee/mcp-codecov)\n[![codecov](https://codecov.io/gh/egulatee/mcp-server-codecov/branch/main/graph/badge.svg)](https://codecov.io/gh/egulatee/mcp-server-codecov)\n![Test and Coverage](https://github.com/egulatee/mcp-server-codecov/workflows/Test%20and%20Coverage/badge.svg)\n[![Security Policy](https://img.shields.io/badge/Security-Policy-blue.svg)](https://github.com/egulatee/mcp-server-codecov/security/policy)\n![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)\n![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)\n![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg)\n![MCP](https://img.shields.io/badge/MCP-Server-orange.svg)\n\nA 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.\n\n📦 **Published on npm:** [@egulatee/mcp-codecov](https://www.npmjs.com/package/@egulatee/mcp-codecov)\n🐳 **Docker image:** [ghcr.io/egulatee/mcp-server-codecov](https://github.com/egulatee/mcp-server-codecov/pkgs/container/mcp-server-codecov)\n\n> **📖 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/).\n\n## Quick Start (Claude Code)\n\nGet started in under 2 minutes:\n\n### 1. Get your Codecov API token\n\nCreate an API token (not an upload token) from your Codecov account:\n\n1. Go to [codecov.io](https://codecov.io) (or your self-hosted URL)\n2. Click your avatar → Settings → Access tab\n3. Click \"Generate Token\" and name it \"MCP Server API Access\"\n4. Copy the token value\n\n### 2. Set your environment variable\n\nAdd to your shell profile (`~/.zshrc` or `~/.bashrc`):\n\n```bash\nexport CODECOV_TOKEN=\"your-api-token-here\"\n```\n\nThen reload: `source ~/.zshrc`\n\n### 3. Install the MCP server\n\n```bash\nclaude mcp add --transport stdio codecov \\\n  --env CODECOV_BASE_URL=https://codecov.io \\\n  --env CODECOV_TOKEN=${CODECOV_TOKEN} \\\n  -- npx -y @egulatee/mcp-codecov\n```\n\n### 4. Verify installation\n\n```bash\nclaude mcp get codecov\n```\n\nExpected output: `codecov: @egulatee/mcp-codecov - ✓ Connected`\n\n**That's it!** You can now use Codecov tools in Claude Code. See [Available Tools](#available-tools) below.\n\n---\n\n## Features\n\n- **File-level coverage**: Get detailed line-by-line coverage data for specific files\n- **Commit coverage**: Retrieve coverage statistics for individual commits\n- **Repository coverage**: Get overall coverage metrics for repositories\n- **Pull request coverage**: Analyze coverage changes and impact for pull requests\n- **Coverage comparison**: Compare coverage between branches, commits, or tags\n- **Configurable URL**: Point to any Codecov instance (codecov.io or self-hosted)\n- **Token authentication**: API token support for accessing coverage data\n\n## Token Types\n\n**Important**: Codecov has two different types of tokens:\n\n- **Upload Token**: Used for pushing coverage reports TO Codecov during CI/CD. Found on your repository's Settings → General page.\n- **API Token**: Used for reading coverage data FROM Codecov via the API. Created in your Codecov Settings → Access tab.\n\nThis MCP server requires an **API token**, not an upload token.\n\n## Available Tools\n\n### get_file_coverage\n\nGet line-by-line coverage data for a specific file.\n\n**Parameters:**\n- `owner` (required): Repository owner (username or organization)\n- `repo` (required): Repository name\n- `file_path` (required): Path to the file within the repository (e.g., 'src/index.ts')\n- `ref` (optional): Git reference (branch, tag, or commit SHA)\n\n**Example:**\n```\nGet coverage for src/index.ts in owner/repo on main branch\n```\n\n### get_commit_coverage\n\nGet coverage data for a specific commit.\n\n**Parameters:**\n- `owner` (required): Repository owner\n- `repo` (required): Repository name\n- `commit_sha` (required): Commit SHA\n\n**Example:**\n```\nGet coverage for commit abc123 in owner/repo\n```\n\n### get_repo_coverage\n\nGet overall coverage statistics for a repository.\n\n**Parameters:**\n- `owner` (required): Repository owner\n- `repo` (required): Repository name\n- `branch` (optional): Branch name (defaults to repository's default branch)\n\n**Example:**\n```\nGet overall coverage for owner/repo on main branch\n```\n\n### get_pull_request_coverage\n\nGet coverage data for a specific pull request, including coverage changes and file-level impact.\n\n**Parameters:**\n- `owner` (required): Repository owner (username or organization)\n- `repo` (required): Repository name\n- `pull_number` (required): Pull request number\n\n**Example:**\n```\nGet coverage for pull request #123 in owner/repo\n```\n\n**Use Cases:**\n- Check if PR meets coverage thresholds before approving\n- Alert when PR decreases overall coverage\n- Identify which files in a PR lack coverage\n- Implement quality gates that block merges if coverage drops\n\n### compare_coverage\n\nCompare coverage between two git references (branches, commits, or tags).\n\n**Parameters:**\n- `owner` (required): Repository owner (username or organization)\n- `repo` (required): Repository name\n- `base` (required): Base reference (e.g., 'main', commit SHA)\n- `head` (required): Head reference to compare against base\n\n**Example:**\n```\nCompare coverage between main branch and feature-branch in owner/repo\n```\n\n**Use Cases:**\n- Compare coverage between release branches\n- Analyze coverage changes between any two commits\n- Track coverage trends across development cycles\n- Validate coverage improvements in feature branches\n\n## Repository Activation\n\n**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**.\n\n### Manual Activation Process\n\nTo activate a repository for coverage tracking:\n\n1. Log in to your Codecov instance (e.g., [codecov.io](https://codecov.io))\n2. Navigate to your organization/user account\n3. Find the repository you want to activate\n4. Click the **\"Activate\"** button to enable coverage tracking\n5. Once activated, you can upload coverage reports from your CI/CD pipeline\n\n**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).\n\n## Verification and Troubleshooting\n\n### Common Issues\n\n**1. 401 Unauthorized Error**\n\n- **Check token type**: Ensure you're using an **API token** (from Settings → Access), not an upload token\n- Verify the token is valid and has access to the repository\n- For self-hosted instances, confirm you're using the correct `CODECOV_BASE_URL`\n\n**2. Environment Variable Not Expanding**\n\n- Make sure the variable is exported in your shell (check `~/.zshrc` or `~/.bashrc`)\n- Restart Claude Code after setting environment variables\n- Verify the variable exists: `echo $CODECOV_TOKEN`\n\n**3. Connection Failed**\n\n- Restart Claude Code or Claude Desktop\n- Verify environment variables are set correctly: `echo $CODECOV_TOKEN`\n- Check the configuration: `claude mcp get codecov`\n\n**4. HTTP vs HTTPS**\n\nAlways use `https://` for the `CODECOV_BASE_URL`, not `http://`:\n- Correct: `https://your-codecov-instance.com`\n- Incorrect: `http://your-codecov-instance.com`\n\n## Advanced Configuration\n\n### Self-Hosted Codecov\n\nFor self-hosted Codecov instances, use your instance URL:\n\n```bash\nclaude mcp add --transport stdio codecov \\\n  --env CODECOV_BASE_URL=https://codecov.your-company.com \\\n  --env CODECOV_TOKEN=${CODECOV_TOKEN} \\\n  -- npx -y @egulatee/mcp-codecov\n```\n\n### Claude Desktop Setup\n\nAdd to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"codecov\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@egulatee/mcp-codecov\"],\n      \"env\": {\n        \"CODECOV_BASE_URL\": \"https://codecov.io\",\n        \"CODECOV_TOKEN\": \"your-codecov-token-here\"\n      }\n    }\n  }\n}\n```\n\n### Manual Configuration (Claude Code)\n\nAdd to `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"codecov\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@egulatee/mcp-codecov\"],\n      \"env\": {\n        \"CODECOV_BASE_URL\": \"https://codecov.io\",\n        \"CODECOV_TOKEN\": \"${CODECOV_TOKEN}\"\n      }\n    }\n  }\n}\n```\n\n**Notes**:\n- Environment variable expansion is supported using `${VAR}` syntax\n- Variables like `${CODECOV_TOKEN}` will be read from your shell environment\n- The `-y` flag for npx automatically accepts the package installation prompt\n\n### Docker (no Node.js required)\n\nPull and run the official multi-platform image from GitHub Container Registry:\n\n```bash\ndocker run --rm -i \\\n  -e CODECOV_TOKEN=your_token \\\n  ghcr.io/egulatee/mcp-server-codecov\n```\n\n**Platforms:** `linux/amd64` and `linux/arm64` (Apple Silicon, AWS Graviton)\n\n**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"codecov\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"--rm\", \"-i\",\n        \"-e\", \"CODECOV_TOKEN=your_token\",\n        \"ghcr.io/egulatee/mcp-server-codecov\"\n      ]\n    }\n  }\n}\n```\n\n**With self-hosted Codecov:**\n\n```bash\ndocker run --rm -i \\\n  -e CODECOV_TOKEN=your_token \\\n  -e CODECOV_BASE_URL=https://codecov.your-company.com \\\n  ghcr.io/egulatee/mcp-server-codecov\n```\n\n**Available tags:** `latest`, `2`, `2.1`, `2.1.0` (full semver)\n\n**stdio bridge with socat:**\n\nThe 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:\n\n```bash\n# Start the server exposing a TCP port\ndocker run --rm -p 3000:3000 \\\n  -e CODECOV_TOKEN=your_token \\\n  ghcr.io/egulatee/mcp-server-codecov\n\n# Bridge stdio ↔ TCP in a second terminal (or from your MCP client config)\nsocat TCP:localhost:3000 STDIO\n```\n\n> **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).\n\n### Installing from npm Globally\n\n```bash\nnpm install -g @egulatee/mcp-codecov\n```\n\n**Benefits:**\n- Simple one-command installation\n- Automatic updates with `npm update -g @egulatee/mcp-codecov`\n- No manual build steps required\n- Works across all projects\n\n**Verify installation:**\n```bash\nnpm list -g @egulatee/mcp-codecov\nwhich mcp-codecov\nnpm view @egulatee/mcp-codecov version\n```\n\n### Development Installation (Source)\n\nOnly use this method if you're contributing to the project:\n\n```bash\ngit clone https://github.com/egulatee/mcp-server-codecov.git\ncd mcp-server-codecov\nnpm install\nnpm run build\n```\n\nThen configure with the built path:\n\n**Claude Code CLI:**\n```bash\nclaude mcp add --transport stdio codecov \\\n  --env CODECOV_BASE_URL=https://codecov.io \\\n  --env CODECOV_TOKEN=${CODECOV_TOKEN} \\\n  -- node /absolute/path/to/codecov-mcp/dist/index.js\n```\n\n**Manual (`~/.claude.json`):**\n```json\n{\n  \"mcpServers\": {\n    \"codecov\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/codecov-mcp/dist/index.js\"],\n      \"env\": {\n        \"CODECOV_BASE_URL\": \"https://codecov.io\",\n        \"CODECOV_TOKEN\": \"${CODECOV_TOKEN}\"\n      }\n    }\n  }\n}\n```\n\n**Claude Desktop:**\n```json\n{\n  \"mcpServers\": {\n    \"codecov\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-server-codecov/dist/index.js\"],\n      \"env\": {\n        \"CODECOV_BASE_URL\": \"https://codecov.io\",\n        \"CODECOV_TOKEN\": \"your-codecov-token-here\"\n      }\n    }\n  }\n}\n```\n\n## Testing\n\nThis project maintains 97%+ code coverage with comprehensive unit tests using Vitest.\n\nFor detailed testing documentation, including how to run tests, coverage requirements, CI integration, and writing tests, see **[TESTING.md](TESTING.md)**.\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Watch mode for development\nnpm run watch\n```\n\n## Release Process\n\nThis project uses an automated release workflow via GitHub Actions. Releases are published to npm automatically when you push a version tag.\n\nFor detailed release instructions, including prerequisites, creating releases, manual releases, and version numbering, see **[RELEASE.md](RELEASE.md)**.\n\n## API Compatibility\n\nThis server uses Codecov's API v2. The API endpoints follow this pattern:\n\n- File coverage: `/api/v2/gh/{owner}/repos/{repo}/file_report/{file_path}`\n- Commit coverage: `/api/v2/gh/{owner}/repos/{repo}/commits/{commit_sha}`\n- Repository coverage: `/api/v2/gh/{owner}/repos/{repo}`\n- Pull request coverage: `/api/v2/gh/{owner}/repos/{repo}/pulls/{pull_number}`\n- Coverage comparison: `/api/v2/gh/{owner}/repos/{repo}/compare/{base}...{head}`\n\nCurrently supports GitHub repositories (`gh`). Support for other providers (GitLab, Bitbucket) can be added by modifying the API paths.\n\n## Resources\n\n- 📝 [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\n\n## License\n\nMIT\n",
  "bytes": 13503,
  "sha": "56e588187f698cc2a687f704a01c6b1390a0c6d6110f035eb370d03c87964977",
  "repo_slug": "egulatee/mcp-server-codecov",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_egulatee_codecov_c844ed44/readme"
}