codecov

Codecov 的 MCP 服务

一个模型上下文协议（MCP）服务，提供用于查询 Codecov 覆盖率数据的工具。支持 codecov.io 和可自托管的 Codecov 实例，并可配置 URL 端点。

📦 已发布到 npm： @egulatee/mcp-codecov 🐳 Docker 镜像： ghcr.io/egulatee/mcp-server-codecov

📖 了解更多：阅读关于如何在短短 2 小时内使用 AI 构建此 MCP 服务。

快速开始（Claude Code）

不到 2 分钟即可开始：

1. 获取 Codecov API 令牌

在你的 Codecov 账户中创建 API 令牌（而非上传令牌）：

1. 前往 codecov.io（或你的可自托管实例 URL）
2. 点击头像 → Settings → Access 标签页
3. 点击“Generate Token”，并将其命名为“MCP Server API Access”
4. 复制令牌值

2. 设置环境变量

将以下内容添加到你的 shell 配置文件（~/.zshrc 或 ~/.bashrc）：

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

然后重新加载：source ~/.zshrc

3. 安装 MCP 服务

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

4. 验证安装

claude mcp get codecov

预期输出：codecov: @egulatee/mcp-codecov - ✓ Connected

就这么简单！ 现在你可以在 Claude Code 中使用 Codecov 工具。请参阅下文的可用工具。

---

功能

• 文件级覆盖率：获取特定文件详细的逐行覆盖率数据
• 提交覆盖率：获取单个提交的覆盖率统计信息
• 仓库覆盖率：获取仓库的整体覆盖率指标
• 拉取请求覆盖率：分析拉取请求的覆盖率变化和影响
• 覆盖率比较：比较不同分支、提交或标签之间的覆盖率
• 可配置 URL：可连接到任意 Codecov 实例（codecov.io 或可自托管实例）
• 令牌身份验证：支持使用 API 令牌访问覆盖率数据

令牌类型

重要提示：Codecov 有两种不同类型的令牌：

• 上传令牌：在 CI/CD 期间用于将覆盖率报告推送到 Codecov。在仓库的 Settings → General 页面中查找。
• API 令牌：用于通过 API 从 Codecov 读取覆盖率数据。在 Codecov 的 Settings → Access 标签页中创建。

此 MCP 服务需要 API 令牌，而非上传令牌。

可用工具

get_file_coverage

获取特定文件的逐行覆盖率数据。

参数：

• owner（必填）：仓库所有者（用户名或组织）
• repo（必填）：仓库名称
• file_path（必填）：仓库内文件的路径（例如，'src/index.ts'）
• ref（可选）：Git 引用（分支、标签或提交 SHA）

示例：

Get coverage for src/index.ts in owner/repo on main branch

get_commit_coverage

获取特定提交的覆盖率数据。

参数：

• owner（必填）：仓库所有者
• repo（必填）：仓库名称
• commit_sha（必填）：提交 SHA

示例：

Get coverage for commit abc123 in owner/repo

get_repo_coverage

获取仓库的总体覆盖率统计信息。

参数：

• owner（必填）：仓库所有者
• repo（必填）：仓库名称
• branch（可选）：分支名称（默认为仓库的默认分支）

示例：

Get overall coverage for owner/repo on main branch

get_pull_request_coverage

获取特定拉取请求的覆盖率数据，包括覆盖率变化和文件级影响。

参数：

• owner（必填）：仓库所有者（用户名或组织）
• repo（必填）：仓库名称
• pull_number（必填）：拉取请求编号

示例：

Get coverage for pull request #123 in owner/repo

使用场景：

• 在批准前检查 PR 是否达到覆盖率阈值
• 在 PR 导致总体覆盖率下降时发出警报
• 找出 PR 中哪些文件缺少覆盖率
• 实施质量门禁，在覆盖率下降时阻止合并

compare_coverage

比较两个 Git 引用（分支、提交或标签）之间的覆盖率。

参数：

• owner（必填）：仓库所有者（用户名或组织）
• repo（必填）：仓库名称
• base（必填）：基准引用（例如，'main'、提交 SHA）
• head（必填）：要与基准进行比较的头部引用

示例：

Compare coverage between main branch and feature-branch in owner/repo

使用场景：

• 比较发布分支之间的覆盖率
• 分析任意两个提交之间的覆盖率变化
• 跟踪不同开发周期中的覆盖率趋势
• 验证功能分支中的覆盖率改进

仓库激活

重要说明：仓库要接收覆盖率上传，必须先在 Codecov 中激活。这是一次性设置步骤，无法通过 API 自动完成。

手动激活流程

要激活仓库以跟踪覆盖率：

1. 登录你的 Codecov 实例（例如，codecov.io）
2. 前往你的组织或用户账户
3. 找到要激活的仓库
4. 点击 “Activate” 按钮以启用覆盖率跟踪
5. 激活后，你可以从 CI/CD 流水线上传覆盖率报告

需要手动激活的原因：Codecov API v2 不提供 /activate 端点。必须通过 Web UI 激活仓库，或者根据你的 Codecov 配置，在首次上传覆盖率时自动激活。

验证与故障排除

常见问题

1. 401 未授权错误

• 检查令牌类型：确保使用的是API 令牌（位于 Settings → Access），而不是上传令牌
• 确认令牌有效且有权访问该仓库
• 对于可自托管实例，请确认使用了正确的 CODECOV_BASE_URL

2. 环境变量未展开

• 确保已在 shell 中导出变量（检查 ~/.zshrc 或 ~/.bashrc）
• 设置环境变量后，重启 Claude Code
• 验证变量是否存在：echo $CODECOV_TOKEN

3. 连接失败

• 重启 Claude Code 或 Claude Desktop
• 确认环境变量已正确设置：echo $CODECOV_TOKEN
• 检查配置：claude mcp get codecov

4. HTTP 与 HTTPS

CODECOV_BASE_URL 始终使用 https://，而不是 http://：

• 正确：https://your-codecov-instance.com
• 错误：http://your-codecov-instance.com

高级配置

可自托管的 Codecov

对于可自托管的 Codecov 实例，请使用你的实例 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 设置

将以下内容添加到 Claude Desktop 配置文件：

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

手动配置（Claude Code）

添加到 ~/.claude.json：

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

说明：

• 支持使用 ${VAR} 语法展开环境变量
• ${CODECOV_TOKEN} 等变量将从 shell 环境中读取
• npx 的 -y 标志会自动接受软件包安装提示

Docker（无需 Node.js）

从 GitHub Container Registry 拉取并运行官方多平台镜像：

docker run --rm -i \
  -e CODECOV_TOKEN=your_token \
  ghcr.io/egulatee/mcp-server-codecov

平台： linux/amd64 和 linux/arm64（Apple Silicon、AWS Graviton）

Claude Desktop（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

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

使用自托管的 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

可用标签： latest、2、2.1、2.1.0（完整语义化版本）

使用 socat 的 stdio 桥接：

Docker 镜像包含 socat，可让通过 stdio 通信的 MCP 客户端经由 TCP 套接字连接到容器内运行的服务：

# 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

注意： 运行桥接命令的主机上也必须安装 socat。可通过 brew install socat（macOS）、apt install socat（Debian/Ubuntu）或 apk add socat（Alpine）进行安装。

从 npm 全局安装

npm install -g @egulatee/mcp-codecov

优点：

• 只需一条命令即可轻松安装
• 通过 npm update -g @egulatee/mcp-codecov 自动更新
• 无需手动构建
• 适用于所有项目

验证安装：

npm list -g @egulatee/mcp-codecov
which mcp-codecov
npm view @egulatee/mcp-codecov version

开发安装（源码）

仅在为项目贡献代码时使用此方法：

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

然后使用构建后的路径进行配置：

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

手动配置（~/.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"
      }
    }
  }
}

测试

本项目使用 Vitest 进行全面的单元测试，代码覆盖率保持在 97% 以上。

有关测试的详细文档，包括如何运行测试、覆盖率要求、CI 集成和编写测试，请参阅 TESTING.md。

开发

# Install dependencies
npm install

# Build the project
npm run build

# Watch mode for development
npm run watch

发布流程

本项目通过 GitHub Actions 使用自动化发布工作流。推送版本标签时，会自动将版本发布到 npm。

有关发布的详细说明，包括前置条件、创建发布、手动发布和版本编号，请参阅 RELEASE.md。

API 兼容性

此服务使用 Codecov 的 API v2。API 端点遵循以下模式：

• 文件覆盖率：/api/v2/gh/{owner}/repos/{repo}/file_report/{file_path}
• 提交覆盖率：/api/v2/gh/{owner}/repos/{repo}/commits/{commit_sha}
• 仓库覆盖率：/api/v2/gh/{owner}/repos/{repo}
• 拉取请求覆盖率：/api/v2/gh/{owner}/repos/{repo}/pulls/{pull_number}
• 覆盖率比较：/api/v2/gh/{owner}/repos/{repo}/compare/{base}...{head}

目前支持 GitHub 仓库（gh）。如需支持其他提供商（GitLab、Bitbucket），可修改 API 路径。

资源

• 📝 2 小时内构建 Codecov MCP 服务 - 详细介绍如何使用 AI 增强开发技术开发此服务

许可证

MIT