CircleCI MCP サーバー
モデルコンテキストプロトコル（MCP）は、大規模言語モデル（LLM）と外部システム間のコンテキストを管理するための新しい標準化プロトコルです。このリポジトリでは、 CircleCI用のMCPサーバーを提供します。
これにより、Cursor IDE、Windsurf、Copilot、または MCP でサポートされている任意のクライアントを使用して、自然言語で CircleCI で次の操作を実行できるようになります。
https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74
要件
NPX インストールの場合:
- pnpm パッケージマネージャー -詳細はこちら
- Node.js >= v18.0.0
Docker インストールの場合:
インストール
カーソル
NPXの使用
カーソル MCP 構成に以下を追加します。
{
"mcpServers": {
"circleci-mcp-server": {
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci"],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
Dockerの使用
カーソル MCP 構成に以下を追加します。
{
"mcpServers": {
"circleci-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "CIRCLECI_TOKEN",
"-e", "CIRCLECI_BASE_URL",
"circleci:mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
VSコード
NPXの使用
.vscode/mcp.jsonに VS Code 用の CircleCI MCP Server をインストールするには:
{
// 💡 Inputs are prompted on first server start, then stored securely by VS Code.
"inputs": [
{
"type": "promptString",
"id": "circleci-token",
"description": "CircleCI API Token",
"password": true
},
{
"type": "promptString",
"id": "circleci-base-url",
"description": "CircleCI Base URL",
"default": "https://circleci.com"
}
],
"servers": {
// https://github.com/ppl-ai/modelcontextprotocol/
"circleci-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci"],
"env": {
"CIRCLECI_TOKEN": "${input:circleci-token}",
"CIRCLECI_BASE_URL": "${input:circleci-base-url}"
}
}
}
}
Dockerの使用
Docker を使用して.vscode/mcp.jsonに VS Code 用の CircleCI MCP Server をインストールするには:
{
// 💡 Inputs are prompted on first server start, then stored securely by VS Code.
"inputs": [
{
"type": "promptString",
"id": "circleci-token",
"description": "CircleCI API Token",
"password": true
},
{
"type": "promptString",
"id": "circleci-base-url",
"description": "CircleCI Base URL",
"default": "https://circleci.com"
}
],
"servers": {
// https://github.com/ppl-ai/modelcontextprotocol/
"circleci-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "CIRCLECI_TOKEN",
"-e", "CIRCLECI_BASE_URL",
"circleci:mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "${input:circleci-token}",
"CIRCLECI_BASE_URL": "${input:circleci-base-url}"
}
}
}
}
クロードデスクトップ
NPXの使用
claude_desktop_config.json に次の内容を追加します。
{
"mcpServers": {
"circleci-mcp-server": {
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci"],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
Dockerの使用
claude_desktop_config.json に次の内容を追加します。
{
"mcpServers": {
"circleci-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "CIRCLECI_TOKEN",
"-e", "CIRCLECI_BASE_URL",
"circleci:mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
このファイルを見つける/作成するには、まずClaudeデスクトップの設定を開きます。次に、設定パネルの左側のバーにある「開発」をクリックし、「設定の編集」をクリックします。
これにより、次の場所に構成ファイルが作成されます。
- macOS: ~/ライブラリ/アプリケーションサポート/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Claude Desktop で MCP サーバーを使用する方法の詳細については、以下のガイドを参照してください: https://modelcontextprotocol.io/quickstart/user
クロード・コード
NPXの使用
Claude Code をインストールした後、次のコマンドを実行します。
claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci
Dockerの使用
Claude Code をインストールした後、次のコマンドを実行します。
claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -e CIRCLECI_BASE_URL=https://circleci.com -- docker run --rm -i -e CIRCLECI_TOKEN -e CIRCLECI_BASE_URL circleci:mcp-server-circleci
Claude Code で MCP サーバーを使用する方法の詳細については、以下のガイドを参照してください: https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp
ウィンドサーフィン
NPXの使用
windsurf mcp_config.json に以下を追加します。
{
"mcpServers": {
"circleci-mcp-server": {
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci"],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
Dockerの使用
windsurf mcp_config.json に以下を追加します。
{
"mcpServers": {
"circleci-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "CIRCLECI_TOKEN",
"-e", "CIRCLECI_BASE_URL",
"circleci:mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
Windsurf で MCP サーバーを使用する方法の詳細については、以下のガイドを参照してください: https://docs.windsurf.com/windsurf/mcp
Smithery経由でインストール
Smithery経由で Claude Desktop 用の CircleCI MCP Server を自動的にインストールするには:
npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude
特徴
サポートされているツール
get_build_failure_logsCircleCI ビルドから詳細な失敗ログを取得します。このツールは次の 3 つの方法で使用できます。- プロジェクトスラッグとブランチの使用（推奨ワークフロー）:
- まず、利用可能なプロジェクトをリストします。
- list_followed_projectsツールを使用してプロジェクトを取得します
- 例:「CircleCI プロジェクトの一覧を表示する」
- 次に、プロジェクトスラッグが関連付けられているプロジェクトを選択します。
- 例:「my-project を使ってみましょう」
- 次に、特定のブランチのビルド失敗ログを取得するように要求します。
- 例:「メインブランチの my-project のビルド失敗を取得する」
- CircleCI URL の使用:
- ローカル プロジェクト コンテキストの使用:
- 以下を提供することで、ローカル ワークスペースから作業できます。
- ワークスペースのルートパス
- GitリモートURL
- 支店名
- 例: 「現在のブランチで最後に失敗したパイプラインを見つける」
このツールは、次のようなフォーマットされたログを返します。
- ジョブ名
- ステップバイステップの実行の詳細
- 失敗メッセージとコンテキスト
これは特に次の場合に役立ちます:
- 失敗したビルドのデバッグ
- テストの失敗を分析する
- 展開の問題の調査
- IDEを離れずにビルドログに素早くアクセス
find_flaky_testsテスト実行履歴を分析し、CircleCIプロジェクト内の不安定なテストを特定します。この機能は、https: //circleci.com/blog/introducing-test-insights-with-flaky-test-detection/#flaky-test-detectionで説明されている不安定なテスト検出機能を活用します。このツールは次の 3 つの方法で使用できます。- プロジェクトスラッグの使用（推奨ワークフロー）:
- まず、利用可能なプロジェクトをリストします。
- list_followed_projectsツールを使用してプロジェクトを取得します
- 例:「CircleCI プロジェクトの一覧を表示する」
- 次に、projectSlugが関連付けられているプロジェクトを選択します。
- 例:「my-project を使ってみましょう」
- 次に、不安定なテストを取得するように要求します。
- 例: 「my-project の不安定なテストを取得する」
- CircleCI プロジェクト URL の使用:
- ローカル プロジェクト コンテキストの使用:
- 以下を提供することで、ローカル ワークスペースから作業できます。
- 例: 「現在のプロジェクトで不安定なテストを見つける」
このツールは、次のような不安定なテストに関する詳細な情報を返します。
- テスト名とファイルの場所
- 失敗メッセージとコンテキスト
これは次のことに役立ちます:
- テストスイート内の信頼性の低いテストを特定する
- テストの失敗に関する詳細なコンテキストを取得する
- テストの改善についてデータに基づいた意思決定を行う
get_latest_pipeline_status指定されたブランチの最新のパイプラインのステータスを取得します。このツールは3つの方法で使用できます。- プロジェクトスラッグとブランチの使用（推奨ワークフロー）:
- まず、利用可能なプロジェクトをリストします。
- list_followed_projectsツールを使用してプロジェクトを取得します
- 例:「CircleCI プロジェクトの一覧を表示する」
- 次に、projectSlugが関連付けられているプロジェクトを選択します。
- 例:「my-project を使ってみましょう」
- 次に、特定のブランチの最新のパイプライン ステータスを取得するように要求します。
- 例:「メインブランチの my-project の最新パイプラインのステータスを取得する」
- CircleCI プロジェクト URL の使用:
- ローカル プロジェクト コンテキストの使用:
- 以下を提供することで、ローカル ワークスペースから作業できます。
- ワークスペースのルートパス
- GitリモートURL
- 支店名
- 例: 「現在のプロジェクトの最新のパイプラインのステータスを取得する」
ツールは最新のパイプラインのフォーマットされたステータスを返します。
- ワークフロー名と現在のステータス
- 各ワークフローの所要時間
- 作成と完了のタイムスタンプ
- パイプライン全体の健全性
出力例:
---
Workflow: build
Status: success
Duration: 5 minutes
Created: 4/20/2025, 10:15:30 AM
Stopped: 4/20/2025, 10:20:45 AM
---
Workflow: test
Status: running
Duration: unknown
Created: 4/20/2025, 10:21:00 AM
Stopped: in progress
これは特に次の場合に役立ちます:
- 最新のパイプラインのステータスを確認する
- 特定のブランチの最新パイプラインのステータスを取得する
- IDEを離れずに最新のパイプラインのステータスを素早く確認
get_job_test_resultsCircleCIジョブのテストメタデータを取得し、IDEを離れることなくテスト結果を分析できます。このツールは以下の3つの方法で使用できます。- プロジェクトスラッグとブランチの使用（推奨ワークフロー）:
- まず、利用可能なプロジェクトをリストします。
- list_followed_projectsツールを使用してプロジェクトを取得します
- 例:「CircleCI プロジェクトの一覧を表示する」
- 次に、projectSlugが関連付けられているプロジェクトを選択します。
- 例:「my-project を使ってみましょう」
- 次に、特定のブランチのテスト結果を取得するように要求します。
- 例:「メインブランチの my-project のテスト結果を取得する」
- CircleCI URL の使用:
- ローカル プロジェクト コンテキストの使用:
- 以下を提供することで、ローカル ワークスペースから作業できます。
- ワークスペースのルートパス
- GitリモートURL
- 支店名
- 例:「メインブランチ上の現在のプロジェクトのテスト結果を取得する」
ツールは詳細なテスト結果情報を返します。
- すべてのテストの概要（合計、成功、失敗）
- 失敗したテストに関する詳細情報:
- テスト名とクラス
- ファイルの場所
- エラーメッセージ
- 実行時間
- 成功したテストのリストとタイミング情報
- テスト結果でフィルタリング
これは特に次の場合に役立ちます:
- CircleCI ウェブ UI にアクセスせずにテストの失敗を迅速に分析
- テスト失敗のパターンの特定
- 最適化が必要な可能性のある遅いテストを見つける
- プロジェクト全体のテスト範囲を確認する
- 不安定なテストのトラブルシューティング
注: このツールを使用するには、CircleCI の設定でテストメタデータが適切に設定されている必要があります。テストメタデータの収集設定の詳細については、 https ://circleci.com/docs/collect-test-data/ をご覧ください。
config_helperCircleCI の設定タスクをガイダンスと検証で支援します。このツールは以下のことに役立ちます。- CircleCI 構成を検証します。
- .circleci/config.yml の構文エラーとセマンティックエラーをチェックします
- 例:「CircleCI の設定を検証する」
このツールは以下を提供します:
これは次のことに役立ちます:
- プッシュする前に設定エラーをキャッチする
- CircleCI の設定のベストプラクティスを学ぶ
- 構成の問題のトラブルシューティング
- CircleCIの機能を正しく実装する
create_prompt_templateAI対応アプリケーションの機能要件に基づいて、構造化されたプロンプトテンプレートを生成するのに役立ちます。このツールは以下の機能を提供します。- 機能要件を構造化されたプロンプトに変換します。
- ユーザーの要件を最適化されたプロンプトテンプレートに変換します
- 例: 「年齢とトピック別に就寝時のお話を生成するためのプロンプトテンプレートを作成する」
このツールは以下を提供します:
- 構造化されたプロンプトテンプレート
- 必要な入力パラメータを定義するコンテキストスキーマ
これは次のことに役立ちます:
- AIアプリケーションに効果的なプロンプトを作成する
- 一貫した結果を得るために入力パラメータを標準化する
- 堅牢なAI搭載機能を構築する
recommend_prompt_template_testsプロンプトテンプレートのテストケースを生成し、期待通りの結果が得られるかを確認します。このツールは以下の機能を備えています。- プロンプト テンプレートのテスト ケースを提供します。
- プロンプトテンプレートとコンテキストスキーマに基づいて多様なテストシナリオを作成します
- 例: 「就寝時のストーリープロンプトテンプレートのテストを生成する」
このツールは以下を提供します:
- 推奨されるテストケースの配列
- テンプレートの堅牢性をテストするためのさまざまなパラメータの組み合わせ
これは次のことに役立ちます:
- プロンプトテンプレートの機能を検証する
- 入力全体にわたって一貫したAI応答を確保する
- エッジケースと潜在的な問題を特定する
- AIアプリケーション全体の品質を向上
list_followed_projectsCircleCIでユーザーがフォローしているすべてのプロジェクトを一覧表示します。このツールは以下の機能を提供します。- プロジェクトを取得して表示します:
- ユーザーがアクセスでき、フォローしているすべてのプロジェクトを表示します
- 各エントリにプロジェクト名とプロジェクトスラッグを提供します
- 例:「CircleCI プロジェクトの一覧を表示する」
ツールはフォーマットされたプロジェクトのリストを返します。出力例:
Projects followed:
1. my-project (projectSlug: gh/organization/my-project)
2. another-project (projectSlug: gh/organization/another-project)
これは特に次の場合に役立ちます:
- 利用可能な CircleCI プロジェクトを特定する
- 他の CircleCI ツールに必要な projectSlug を取得する
- 後続の操作のためのプロジェクトの選択
注: projectSlug (プロジェクト名ではありません) は他の多くの CircleCI ツールに必須であり、プロジェクトを選択した後にそれらのツールの呼び出しに使用されます。
run_pipelineパイプラインの実行をトリガーします。このツールは次の3つの方法で使用できます。- プロジェクトスラッグとブランチの使用（推奨ワークフロー）:
- まず、利用可能なプロジェクトをリストします。
- list_followed_projectsツールを使用してプロジェクトを取得します
- 例:「CircleCI プロジェクトの一覧を表示する」
- 次に、projectSlugが関連付けられているプロジェクトを選択します。
- 例:「my-project を使ってみましょう」
- 次に、特定のブランチに対してパイプラインを実行するように要求します。
- 例:「メインブランチで my-project のパイプラインを実行する」
- CircleCI URL の使用:
- ローカル プロジェクト コンテキストの使用:
- 以下を提供することで、ローカル ワークスペースから作業できます。
- ワークスペースのルートパス
- GitリモートURL
- 支店名
- 例:「メインブランチで現在のプロジェクトのパイプラインを実行する」
このツールは、パイプラインの実行を監視するためのリンクを返します。
これは特に次の場合に役立ちます:
- CircleCI の Web UI にアクセスせずにパイプラインをすばやく実行
- 特定のブランチからパイプラインを実行する
発達
はじめる
- リポジトリをクローンします。
git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
cd mcp-server-circleci
- 依存関係をインストールします:
- プロジェクトをビルドします。
Dockerコンテナの構築
次のコマンドを使用して、Docker コンテナをローカルでビルドできます。
docker build -t circleci:mcp-server-circleci .
これにより、任意の MCP クライアントで使用できるcircleci:mcp-server-circleciとしてタグ付けされた Docker イメージが作成されます。
コンテナを実行するには:
docker run --rm -i -e CIRCLECI_TOKEN=your-circleci-token -e CIRCLECI_BASE_URL=https://circleci.com circleci:mcp-server-circleci
MCP Inspectorを使用した開発
MCPサーバーで反復処理を行う最も簡単な方法は、MCPインスペクターを使用することです。MCPインスペクターの詳細については、 https://modelcontextprotocol.io/docs/tools/inspectorをご覧ください。
- 開発サーバーを起動します。
pnpm watch # Keep this running in one terminal
- 別のターミナルで、インスペクターを起動します。
- 環境を構成します。
- インスペクターUIの環境変数セクションに
CIRCLECI_TOKENを追加します。 - トークンにはCircleCIプロジェクトへの読み取りアクセス権が必要です
- オプションでCircleCIのベースURLを設定できます。デフォルトは
https//circleci.comです。
テスト
- テスト スイートを実行します。
- 開発中にウォッチモードでテストを実行します。
より詳しい貢献ガイドラインについては、 CONTRIBUTING.mdをご覧ください。