↓Skip to main content

Codecov MCP Server

Project Overview #

Timeline: December 2025 (2 Hours Total)

The Codecov MCP Server is a production-ready Model Context Protocol (MCP) server that enables Claude Code and other AI assistants to query Codecov coverage data directly. Built in just 2 hours using AI-assisted development, this project demonstrates how modern AI tools can accelerate developer productivity while maintaining production-quality standards.

The project solved a real pain point: the existing third-party MCP server for Codecov was archived and lacked support for self-hosted instances. Rather than forking an abandoned project, this build-from-scratch approach delivered enterprise features, comprehensive testing, and maintainable code in a fraction of the time traditional development would require.

Key Achievement: Published to npm as mcp-server-codecov with 100% test coverage, replacing an archived solution with a more capable, enterprise-ready tool.

Project Context #

The Problem #

  • Existing MCP server for Codecov was archived (no longer maintained)
  • Archived solution only supported codecov.io cloud instances
  • No support for self-hosted Codecov Enterprise deployments
  • Developers needed to context-switch away from Claude Code to check coverage data
  • No reliable way for AI assistants to access test coverage metrics

The Opportunity #

  • Model Context Protocol (MCP) is Anthropic’s emerging standard for AI tool integration
  • Building MCP servers positions developers at the cutting edge of AI-native tooling
  • Rapid development using AI assistance proves the concept: AI building tools for AI
  • Open-source contribution to growing MCP ecosystem

The Approach #

Build a production-ready replacement from scratch in a time-boxed 2-hour session using AI-assisted development (Claude Code), with emphasis on:

  • Speed: MVP in 30 minutes, production-ready in 2 hours
  • Quality: 100% test coverage, comprehensive documentation
  • Enterprise support: Configurable for both cloud and self-hosted instances
  • Maintainability: TypeScript with clear architecture, ready for community contributions

Technical Architecture #

Tech Stack #

  • Language: TypeScript 5.7+ (type-safe, modern async/await)
  • Framework: MCP SDK (@modelcontextprotocol/sdk)
  • Testing: Vitest with 100% code coverage across all metrics
  • Runtime: Node.js 18.0.0+
  • API Client: Axios for HTTP requests with retry logic
  • Build: TypeScript compiler (tsc) with ES2022 target

Core Architecture #

mcp-server-codecov/
├── src/
│   ├── index.ts           # MCP server initialization & tool registration
│   ├── codecov-client.ts  # Codecov API client with authentication
│   ├── tools.ts           # Tool handlers (file, commit, repo coverage)
│   └── types.ts           # TypeScript interfaces for API responses
├── tests/
│   ├── index.test.ts      # Integration tests for MCP server
│   ├── codecov-client.test.ts  # Unit tests with mocked API calls
│   └── tools.test.ts      # Tool handler validation
└── package.json           # npm package configuration

Implementation Size: 265 lines of core code (excluding tests, config, docs)

MCP Protocol Integration #

The server implements three MCP tools that Claude Code can invoke:

  1. get_file_coverage: Retrieve line-by-line coverage for specific files
  2. get_commit_coverage: Access coverage statistics for specific commits
  3. get_repo_coverage: Obtain aggregate coverage data for entire repositories

API Design Decisions #

  • Configurable base URL: Environment variable CODECOV_BASE_URL supports both codecov.io and self-hosted instances
  • Token authentication: Secure API token handling via CODECOV_TOKEN environment variable
  • GitHub-focused: Current implementation targets GitHub repositories (extensible for GitLab, Bitbucket)
  • Error handling: Comprehensive error messages for authentication failures, network issues, invalid parameters

Development Process #

AI-Assisted Rapid Development #

This project showcases AI building tools for AI - using Claude Code to build an MCP server that extends Claude Code’s capabilities.

Total Development Time: 2 hours

  • MVP Development: 30 minutes (basic API client + MCP tool handlers)
  • Testing & Quality: 1 hour (achieved 100% coverage with Vitest)
  • Documentation & Polish: 30 minutes (350-line README with troubleshooting)

Workflow #

  1. Requirements gathering (5 min): Analyzed archived MCP server, identified gaps
  2. Architecture planning (10 min): Designed TypeScript module structure with AI
  3. Rapid prototyping (30 min): AI-generated initial implementation with MCP SDK integration
  4. Test-driven refinement (1 hour): Wrote comprehensive tests, iterated to 100% coverage
  5. Documentation (30 min): AI-assisted README creation with troubleshooting guide
  6. Publishing (15 min): npm package setup, versioning, release to registry

Development Environment #

  • IDE: VS Code with TypeScript language server
  • AI Assistant: Claude Code for code generation, test writing, documentation
  • Version Control: Git with conventional commits
  • CI/CD: GitHub Actions for automated testing and npm publishing
  • Package Manager: npm for dependency management and publishing

Key Development Decisions #

  • TypeScript over JavaScript: Type safety prevents runtime errors, improves maintainability
  • Vitest over Jest: Faster test execution, better ESM support, modern DX
  • Mocked API tests: Unit tests use mocked Codecov responses for reliability and speed
  • Comprehensive README: Anticipated pain points (auth tokens, base URL config) and documented solutions

Key Features #

Coverage Querying Tools #

File-Level Coverage

  • Retrieve line-by-line coverage data for specific files
  • Parameters: owner, repo, file path, optional commit SHA
  • Returns: detailed coverage map showing covered/uncovered lines
  • Use case: Identify untested code sections during code review

Commit Coverage Analysis

  • Access coverage statistics for specific commits
  • Parameters: owner, repo, commit SHA
  • Returns: aggregate coverage percentages, file-level breakdowns
  • Use case: Track coverage changes in pull requests

Repository Coverage Overview

  • Obtain project-wide coverage metrics
  • Parameters: owner, repo, optional branch
  • Returns: total coverage percentage, trends, historical data
  • Use case: Dashboard-style coverage monitoring

Enterprise Features #

  • Self-hosted support: Configurable base URL for Codecov Enterprise instances
  • Cloud support: Works out-of-box with codecov.io using default configuration
  • Secure authentication: Environment variable-based API token management
  • Error resilience: Comprehensive error handling with actionable messages

Developer Experience #

  • Global CLI installation: npm install -g mcp-server-codecov
  • MCP configuration templates: Copy-paste configs for Claude Desktop and Claude Code
  • Troubleshooting guide: 350-line README addresses common setup issues
  • TypeScript types: Exported types for API responses enable type-safe integrations

Technical Challenges Solved #

Challenge 1: Authentication Token Confusion #

Problem: Initial implementation failed with 401 errors despite having “valid” Codecov credentials.

Root Cause Discovery: Codecov uses two distinct token types:

  • Upload tokens: Used by CI/CD to upload coverage reports (found in Codecov UI settings)
  • API tokens: Used for data access via REST API (requires separate generation)

The team initially used upload tokens, which lack API access permissions.

Solution:

  • Documented token type distinction clearly in README
  • Added troubleshooting section explaining authentication errors
  • Provided step-by-step guide for generating correct API tokens
  • Implemented clear error messages distinguishing auth failures from network issues

Result: Eliminated a 30-minute debugging rabbit hole for future users through proactive documentation.

Challenge 2: Enterprise vs Cloud Support #

Problem: Archived MCP server only worked with codecov.io cloud instances. Teams using self-hosted Codecov Enterprise couldn’t use the tool.

Solution:

  • Made base URL configurable via CODECOV_BASE_URL environment variable
  • Default to https://codecov.io for cloud users (zero-config experience)
  • Override with custom URL for enterprise deployments
  • Documented both use cases with example configurations

Result: Single codebase serves both cloud and enterprise users without forking or conditional logic.

Challenge 3: 100% Test Coverage in 1 Hour #

Problem: Achieve production-quality test coverage within strict 2-hour timeline without compromising code quality.

Solution:

  • Mocked API responses: Used Vitest mocking to simulate Codecov API without network calls
  • AI-assisted test generation: Claude Code generated comprehensive test cases covering edge cases
  • Coverage-driven iteration: Ran vitest --coverage repeatedly, filled gaps until 100%
  • Test structure: Separated unit tests (API client) from integration tests (MCP server)

Result: 100% coverage across statements, branches, functions, and lines in 1 hour of focused development.

Challenge 4: Rapid Documentation for Complex Setup #

Problem: MCP server configuration involves multiple files (Claude Desktop config, Claude Code settings) and environment variables. Poor docs would block adoption.

Solution:

  • AI-generated README: Claude Code drafted 350-line comprehensive guide
  • Copy-paste configs: Provided exact JSON snippets for MCP configuration files
  • Troubleshooting section: Anticipated common issues (wrong token type, base URL misconfiguration)
  • Platform-specific paths: Documented config locations for macOS, Windows, Linux

Result: Zero GitHub issues filed for installation/configuration problems post-launch.

Outcomes & Impact #

Technical Achievements #

  • 100% Test Coverage: All code paths tested (statements, branches, functions, lines)
  • 2-Hour Build: MVP in 30 minutes, production-ready in 2 hours total
  • Published to npm: Available globally as mcp-server-codecov package
  • Zero Dependencies (runtime): Only dev dependencies for testing and building
  • TypeScript Type Safety: Full type coverage prevents runtime errors
  • Comprehensive Documentation: 350-line README with troubleshooting

Developer Productivity Impact #

  • Eliminated context switching: Developers can query coverage without leaving Claude Code
  • AI-native workflow: Claude can proactively identify test gaps during code review
  • Instant coverage feedback: No manual navigation through Codecov web UI
  • PR review enhancement: Coverage data accessible during AI-assisted code reviews

Open Source Contribution #

  • MCP ecosystem growth: Added enterprise-ready tool to Anthropic’s MCP server directory
  • Replaced archived project: Provided actively-maintained alternative to abandoned solution
  • Enterprise adoption: Self-hosted support enables use by regulated industries
  • Community template: Demonstrates rapid MCP server development pattern

AI-Powered Development Validation #

This project proves the AI building tools for AI thesis:

  • 30-minute MVP: AI assistance compressed days of work into minutes
  • Quality maintained: 100% test coverage proves AI can maintain production standards
  • Documentation excellence: 350-line README written with AI assistance
  • Rapid iteration: Coverage gaps identified and filled in minutes, not hours

Development Timeline #

Session 1: Rapid Build (2 Hours Total)

Phase 1: MVP Development (30 Minutes)

  • Requirements analysis and architecture planning (10 min)
  • Codecov API client implementation with authentication (10 min)
  • MCP server setup with SDK integration (5 min)
  • Basic tool handlers for coverage queries (5 min)

Phase 2: Testing & Quality (60 Minutes)

  • Vitest setup and configuration (10 min)
  • Unit tests for API client with mocked responses (20 min)
  • Integration tests for MCP server tools (20 min)
  • Coverage gap analysis and test additions to reach 100% (10 min)

Phase 3: Documentation & Publishing (30 Minutes)

  • Comprehensive README with installation guide (15 min)
  • Troubleshooting section for auth and config issues (10 min)
  • npm package configuration and publishing (5 min)

Post-Launch: Maintenance

  • v1.0.0: Initial release with core features
  • v1.0.1: Bug fix for configuration edge case
  • Ongoing: Community support via GitHub issues (minimal - excellent docs prevent issues)

Tools & Workflow #

  • AI Development: Claude Code for rapid code generation and test writing
  • IDE: VS Code with TypeScript IntelliSense
  • Testing: Vitest with coverage reporting
  • Version Control: Git with conventional commits
  • Publishing: npm registry for global distribution
  • CI/CD: GitHub Actions for automated testing on pull requests

Technologies Used #

  • TypeScript 5.7+: Type-safe development with modern async/await
  • MCP SDK: @modelcontextprotocol/sdk for protocol implementation
  • Vitest: Fast, modern testing framework with coverage reporting
  • Node.js 18+: Runtime environment for MCP server
  • Axios: HTTP client for Codecov API requests
  • npm: Package management and global CLI distribution
  • GitHub Actions: CI/CD for automated testing and publishing

Links & Resources #

Key Takeaways #

This project demonstrates the transformative potential of AI-assisted development for building production-quality developer tools:

  1. AI-Accelerated Speed: 2-hour development from concept to published npm package with 100% test coverage
  2. AI Building Tools for AI: Meta-achievement of using Claude Code to build MCP servers that extend Claude’s capabilities
  3. Quality Without Compromise: AI assistance enables rapid development without sacrificing testing, documentation, or code quality
  4. Enterprise-Ready Delivery: Self-hosted support and comprehensive docs meet production standards
  5. MCP Expertise: Demonstrates specialization in cutting-edge AI tooling ecosystem
  6. Developer Tooling Skills: Ability to identify pain points and ship solutions rapidly
  7. Open Source Impact: Replaced archived project with actively-maintained, more capable alternative

The Future of Development: This project exemplifies the emerging pattern where AI assistance compresses week-long projects into hours while maintaining professional-grade quality standards. The result: developers can ship more tools, faster, with higher quality than ever before.

View on npm → | View on GitHub → | Read Blog Post →