codecov

Codecov 用 MCP サーバー

Codecov のカバレッジデータを照会するためのツールを提供する Model Context Protocol（MCP）サーバーです。設定可能な URL エンドポイントにより、codecov.io とセルフホストの Codecov インスタンスの両方に対応しています。

📦 npm で公開中： @egulatee/mcp-codecov 🐳 Docker イメージ： ghcr.io/egulatee/mcp-server-codecov

📖 詳細はこちら： AI を使ってわずか 2 時間でこの 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. 環境変数を設定する

シェルのプロファイル（~/.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 には異なる種類のトークンが 2 つあります。

• アップロードトークン：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

2 つの git リファレンス（ブランチ、コミット、またはタグ）のカバレッジを比較します。

パラメーター:

• owner（必須）：リポジトリのオーナー（ユーザー名または組織）
• repo（必須）：リポジトリ名
• base（必須）：ベースリファレンス（例：'main'、コミット SHA）
• head（必須）：ベースと比較するヘッドリファレンス

例:

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

ユースケース:

• リリースブランチ間のカバレッジを比較する
• 任意の 2 つのコミット間のカバレッジの変化を分析する
• 開発サイクル全体のカバレッジの傾向を追跡する
• フィーチャーブランチでのカバレッジ改善を検証する

リポジトリの有効化

重要な注意: リポジトリにカバレッジレポートをアップロードするには、事前に Codecov で有効化する必要があります。これは一度だけ行うセットアップで、API 経由では自動化できません。

手動での有効化手順

カバレッジ追跡のためにリポジトリを有効化するには、次の手順を実行します。

1. Codecov インスタンス（例：codecov.io）にログインします
2. 組織またはユーザーのアカウントに移動します
3. 有効化するリポジトリを見つけます
4. **「Activate」**ボタンをクリックして、カバレッジ追跡を有効にします
5. 有効化すると、CI/CD パイプラインからカバレッジレポートをアップロードできます

手動での有効化が必要な理由: Codecov API v2 には /activate エンドポイントがありません。リポジトリの有効化は、Web UI から行う必要があります。または、Codecov の設定によっては、最初のカバレッジレポートのアップロード時に自動で有効化されます。

検証とトラブルシューティング

よくある問題

1. 401 Unauthorized エラー

• トークンの種類を確認する：アップロードトークンではなく、API トークン（Settings → Access から取得）を使用していることを確認します
• トークンが有効で、リポジトリへのアクセス権があることを確認します
• セルフホストインスタンスの場合、正しい CODECOV_BASE_URL を使用していることを確認します

2. 環境変数が展開されない

• シェルで変数がエクスポートされていることを確認します（~/.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 には http:// ではなく、必ず https:// を使用してください。

• 正しい例：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} のような変数は、シェル環境から読み取られます
• 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（完全な semver）

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

メリット：

• 1つのコマンドで簡単にインストールできます
• 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）に対応しています。API パスを変更すれば、ほかのプロバイダー（GitLab、Bitbucket）にも対応できます。

リソース

• 📝 2時間で Codecov MCP サーバーを構築する - AI 拡張開発手法を用いてこのサーバーを開発する詳細な手順

ライセンス

MIT