CircleCI × Cursor 入門：CI/CD ワークフローに AI を取り入れる方法

AI コーディングアシスタントの登場によって、開発者のコーディングやデバッグのスタイルは大きく変わりました。しかし一方で、こうしたアシスタントの多くは CI/CD パイプライン内で何が起きているのかまでは把握できません。ビルドが失敗すると、結局はタブを行き来しながらログを調べ、エラーメッセージをコピーしてエディタに貼り付けるといった作業を繰り返すことになります。

では、もし AI アシスタントが CircleCI と直接連携できたらどうでしょうか。

本チュートリアルでは、AI 搭載コードエディタ「Cursor」を CircleCI MCP サーバー経由で CircleCI に接続する方法を解説します。接続後は、IDE を離れることなく、自然言語で設定ファイルの検証、パイプラインの実行、失敗原因の特定、テスト結果の分析まで行えるようになります。

ここでは Cursor を例に説明しますが、CircleCI MCP サーバーは Claude Desktop、VS Code、Windsurf など、MCP に対応した他のツールでも利用可能です。セットアップの流れは、いずれのツールでもほぼ共通しています。

前提条件

始める前に、以下をご準備ください。

CircleCI アカウント
GitHub アカウント
Node.js 18 以降がローカルにインストールされていること
Cursor がインストールされていること

Cursor とは？

Cursor は VS Code をベースに構築された AI 搭載コードエディタです。見た目や操作感は VS Code に近い一方で、AI による強力な機能が追加されており、コードの作成、リファクタリング、デバッグをよりスピーディーに行えます。

本チュートリアルで主に使用するのは Agent モードです。質問に答えるだけのチャットアシスタントとは異なり、Agent モードでは次のようなことが可能です。

複数ファイルにまたがる変更の実行
ターミナルコマンドの代理実行
コードベース全体のコンテキストの把握
問題が解決するまでの反復的な試行

AI パネルを開くには、Cmd+L（Mac）または Ctrl+L（Windows / Linux）を押します。画面下部にモード選択メニューが表示されるので、Agent を選択してください。本チュートリアルで使用するフル機能が有効になります。

Cursor の機能について詳しく知りたい場合は、Cursor 公式ドキュメントをご覧ください。

CircleCI プロジェクトのセットアップ

MCP サーバーがパイプラインと連携できるようにするには、あらかじめ CircleCI に接続されたプロジェクトを用意し、少なくとも 1 回はパイプラインを実行しておく必要があります。すでにセットアップ済みの場合は、次のセクションに進んでください。

デモ用リポジトリを使用する

このチュートリアルを最も簡単に進める方法は、用意されているデモ用リポジトリを利用することです。Node.js プロジェクトにテストが含まれており、.circleci/config.yml もあらかじめ設定されています。

自分の GitHub アカウントにリポジトリをフォークします。
CircleCI で新規プロジェクトを作成し、フォークしたリポジトリを接続します。
コミットをプッシュしてビルドを実行します（または CircleCI の初回ビルドの自動実行を待ちます）。

CircleCI ダッシュボードにプロジェクトが表示され、パイプラインが少なくとも 1 回実行されていれば、準備完了です。

既存のプロジェクトを使用する場合

既存のプロジェクトを使用する場合は、以下を確認してください。

リポジトリに、パイプラインを定義した .circleci/config.yml ファイルが含まれている
プロジェクトが CircleCI に接続されている
CircleCI ダッシュボードでパイプラインの実行履歴を確認できる

初めて設定を作成する場合は、CircleCI の設定ガイドをご覧ください。

CircleCI MCP サーバーのセットアップ

Model Context Protocol（MCP）は、AI アシスタントが外部ツールやデータソースに接続できるようにするオープン標準です。 CircleCI MCP サーバーはこのプロトコルを利用して、ビルドログ、テスト結果、設定の検証など、AI アシスタントがパイプラインデータへ直接アクセスできるようにします。

次の項目で、Cursor での設定方法を説明します。

ステップ 1：CircleCI Personal API トークンを生成する

AI アシスタントが CircleCI のデータにアクセスするには、パーソナル API トークンによる認証が必要です。

CircleCI にログインする
User Settings → Personal API Tokens に移動する
Create New Token をクリックする
トークンに名前（例：「Cursor MCP」）を付けて作成し、表示されたトークンをコピーする

トークンは次のステップで使用するので、安全な場所に保管してください。詳しくは CircleCI トークンのドキュメントをご覧ください。

ステップ 2：Cursor に MCP 設定を追加する

Cursor では、MCP サーバーの設定を JSON ファイルで管理します。設定はグローバル（すべてのプロジェクト共通）にも、プロジェクト単位にも追加できます。

グローバルで設定する場合は、 ~/.cursor/mcp.json ファイルを作成または編集し、以下を追加してください。

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token"
      }
    }
  }
}

your-circleci-token の部分を、ステップ 1 で生成したトークンに置き換えてください。

ステップ 3：接続を確認する

設定を保存したら、以下の手順で接続を確認します。

Cursor を再起動する（またはウィンドウをリロード）
Cursor Settings → MCP を開く
circleci-mcp-server と利用可能なツールが一覧に表示されていれば成功です

Cursor MCP Settings with CircleCI

ツールが表示されない場合は、MCP 設定パネルの再読み込みアイコンをクリックしてみてください。それでも表示されない場合は、API トークンが有効であること、Node.js 18 以降がインストールされていることを確認してください。

Cursor で CircleCI プロジェクトを指定する

「設定を検証して」「ビルドが失敗した原因は？」といったコマンドを実行するには、MCP サーバーがどの CircleCI プロジェクトを対象にすべきかを知る必要があります。このステップは必要不可欠です。指定しないと、サーバーはどのパイプラインを参照すべきか判断できません。

とはいえ、特別な操作は必要ありません。Cursor で対象プロジェクトのフォルダを開いていれば、MCP サーバーは通常、Git のリモート設定を読み取り、自動的に対応する CircleCI プロジェクトを特定できます。

ステップ 1：Cursor でプロジェクトを開く

Cursor を起動し、CircleCI プロジェクトを含むフォルダを開きます。対象のフォルダは、次の条件を満たす Git リポジトリである必要があります。

GitHub、GitLab、または Bitbucket を指すリモート設定がある
.circleci/config.yml ファイルが含まれている
CircleCI アカウントに対応するプロジェクトが存在する

デモ用リポジトリを使用している場合は、フォークしたリポジトリのコピーを開いてください。

ステップ 2：接続を確認する

AI パネルを開き（Mac は Cmd+L、Windows/Linux は Ctrl+L）、Agent モードに切り替えます。そして、次のように入力します。

List my followed projects on CircleCI

アシスタントが list_followed_projects ツールを使用して、アカウントに紐づくすべての CircleCI プロジェクトを表示します。一覧の中から目的のプロジェクトを探してください。各プロジェクトにはスラッグ（例：gh/your-username/your-repo）が表示されます。

Cursor CircleCI MCP Server Listing Followed CircleCI Projects

プロジェクトが一覧に表示されていれば、設定は完了です。MCP サーバーが、現在の Git のリモート設定とブランチ情報をもとに、対象となる CircleCI プロジェクトを自動的に特定します。

トラブルシューティング

プロジェクトが一覧に表示されない場合は、以下を確認してください。

CircleCI でそのプロジェクトをフォローしていること（CircleCI ダッシュボードに表示されているはずです）
Git リモートが正しく設定されていること（git remote -v で確認）
CircleCI API トークンに必要な権限が付与されていること

ヒント： 現在のディレクトリとは別のプロジェクトを操作したい場合は、プロンプトにプロジェクトの URL またはスラッグを直接指定できます。例：「Get the latest pipeline status for gh/my-org/other-repo」

これで Cursor が対象プロジェクトを認識できるようになりました。次は、この連携機能を実際に活用してみましょう。

ユースケース 1：CircleCI 設定を検証する

まずはシンプルながら非常に実用的な例として、プッシュ前に CircleCI の設定を検証する方法を見ていきましょう。

構文エラーや設定ミスを早い段階で発見できれば、ビルド失敗や不要なパイプライン実行時間の浪費を防げます。CLI コマンドを実行したり、プッシュして結果を確認したりする代わりに、エディタから AI アシスタントへ依頼するだけで検証できます。

AI パネルで次のように入力してみましょう。

Validate my CircleCI config

アシスタントが config_helper ツールを使用して .circleci/config.yml ファイルをチェックします。結果として、次の情報が返されます。

検証結果（成功/失敗）
エラーや警告がある場合はその詳細
設定改善のための推奨事項

CircleCI Cursor Validating CircleCI config file with MCP server

特に、複数のワークフローや Orbs、条件分岐を含む複雑な設定ファイルを編集している場合に、この機能は役立ちます。エディタを離れることなく、その場で即座にフィードバックを得られるため、修正と検証をスムーズに繰り返すことができます。

ユースケース 2：IDE からパイプラインを実行する

コミットをプッシュせずにビルドを実行したい場合もあります。たとえば、インフラ変更の動作確認をしたいときや、不安定なテストの失敗後に再実行したいときなどです。CircleCI MCP サーバーを使えば、自然言語でパイプラインを実行できます。

AI パネルで次のように入力してみましょう。

Run the pipeline for my current branch

Cursor CircleCI MCP Server Running Successful Build

アシスタントが run_pipeline ツールを使用してビルドを実行します。Git リモートやブランチ情報は自動的に読み取られるため、プロジェクトの詳細を指定する必要はありません。実行後は、確認メッセージと、CircleCI 上でパイプラインを確認できるリンクが返されます。

リンクを開けば、CircleCI の UI でパイプラインのステータス確認や操作ができます。ただし多くの場合、開発フローを中断することなく、Cursor 上で必要な情報を取得できます。

CircleCI Pipeline running after being triggered via MCP from Cursor

MCP サーバーにパイプライン実行を依頼する際は、より具体的に指定することもできます。たとえば、実行するブランチを指定する場合は：

Run the pipeline for the develop branch

また、複数のリポジトリをまたいで作業している場合は、プロジェクトの URL を直接指定することもできます。

ユースケース 3：ビルド失敗の原因を特定する

この連携の真価が発揮されるのが、ビルド失敗時です。従来のワークフローは次のようなものでした。

CircleCI を開く → 失敗したパイプラインを探す → ジョブを開く → ログをスクロールする → エラーをコピーする → エディタに貼り付ける → 原因を分析する

MCP サーバーを使えば、これらを Cursor 上で完結できます。ビルドが失敗したら、次のように尋ねてください。

Why did my last build fail?

アシスタントは get_build_failure_logs ツールを呼び出し、直近で失敗したパイプラインから構造化されたデータを取得します。表示される内容は次のとおりです。

どのジョブ／ステップが失敗したか
実行されたコマンドの完全な出力
終了コードとエラーメッセージ
問題の診断に役立つ補足情報

Cursor using CircleCI MCP Server to diagnose latest build failures

Cursor はエラー詳細を取得した後、すぐに内容を解析し、具体的な修正案を提示します。何が原因だったのかを説明し、コードや設定ファイルへの変更案を提案します。

提案を承認すると、Agent モードが直接修正を適用します。コピー＆ペーストは不要です。例えば、依存関係の不足が原因なら、アシスタントが package.json を更新し、npm install を実行してくれます。.circleci/config.yml の設定ミスなら、該当箇所を修正し、変更内容を説明してくれます。

ビルドが通るまで反復する

修正を適用したら、アシスタントに新しいビルドの実行と結果の確認を依頼できます。

Run the pipeline and let me know if it passes

ビルドが再び失敗した場合、アシスタントが新しいエラーログを取得し、次の問題を診断して、追加の修正を提案します。これにより、修正 → ビルド → 確認 → 再修正という高速なフィードバックループを、エディタを離れることなく回せるようになります。

複数回の調整が必要な複雑な問題でも、このワークフローによって「ビルド失敗」から「ビルド成功」までの時間を大幅に短縮できます。

特定のパイプラインを調査したい場合は、URL を直接指定することも可能です。

Get logs from https://app.circleci.com/pipelines/github/my-org/my-repo/123

ユースケース 4：テスト結果を分析する

テストの失敗は、ビルドが壊れる最も一般的な原因の一つです。CircleCI MCP サーバーを使えば、テストのメタデータをエディタに直接取り込み、どのテストがなぜ失敗したのかをすばやく把握できます。次のように依頼してみましょう。

Show me the test results from the last pipeline

アシスタントは get_job_test_results ツールを使用して、以下を含むテストのメタデータを取得します。

テスト名とファイルの場所
成功/失敗のステータス
失敗メッセージやスタックトレース
パフォーマンスメトリクス

Cursor using CircleCI MCP server to check latest pipeline test results

失敗したテストだけを確認したい場合は、フィルタリングもできます。

Show me only the failed tests from the last build

テスト数が多いプロジェクトでは、数百件の成功テストの中から問題箇所を探す手間が省けるため、特に便利です。

おまけ：不安定なテストを検出する

成功したり失敗したりを繰り返す不安定なテストに悩んでいるなら、find_flaky_tests ツールが役立ちます。過去のテスト履歴を分析し、不安定なテストの傾向を特定します。次のように依頼してみてください。

Find flaky tests in my project

不安定なテストの一覧と、その失敗パターンに関するコンテキストが表示されます。これにより、どのテストを優先的に修正すべきか、あるいは隔離すべきかの判断に活用できます。

Cursor から CircleCI CLI コマンドを実行する

MCP サーバーは Cursor を CircleCI のクラウド環境に接続し、実際のパイプライン実行データを取得できるようにします。しかし、場合によってはローカル環境で作業したいこともあります。たとえば、プッシュ前に設定変更を検証したり、デバッグを速めるためにローカルマシンでジョブを実行したりするケースです。

そこで活用できるのが CircleCI CLI です。Cursor の Agent モードはターミナルコマンドを実行できるため、CLI も自然言語で操作できます。

ローカルで設定ファイルを検証する

MCP サーバーの config_helper ツールは、CircleCI のサーバー側で設定を検証します。一方、CLI を使えばオフラインで実行できるローカル検証が可能です。次のように依頼してみましょう。

Run circleci config validate in the terminal

このコマンドは .circleci/config.yml の構文や構造上のエラーをチェックし、API 通信を行わずに結果を返します。設定を編集中に素早く確認したい場合の反復作業に適しています。

ジョブをローカルで実行する

GitHub にプッシュして CircleCI のクラウド実行を待たずに、ジョブの動作を確認したい場合もあります。CircleCI CLI を使えば、ローカルの Docker コンテナ上でジョブを実行できます。次のように依頼してみましょう。

Use the CircleCI CLI to run the build job locally

これにより circleci local execute --job build が実行され、CircleCI の環境を模したコンテナがローカルマシン上で起動します。環境固有の問題のデバッグや、コミット前の変更テストに便利です。

使い分けの目安

用途に応じて、MCP サーバーと CircleCI CLI を使い分けましょう。

アプローチ	適した用途
MCP サーバー	実際のパイプライン状況の確認、ビルドログの取得、CI 実行結果に基づくテスト分析
CircleCI CLI	オフラインでの設定検証、ローカルでのジョブ実行、設定作業中の高速な反復作業

どちらの方法も、Cursor の Agent モードからシームレスに利用できます。まだ CLI をインストールしていない場合は、インストールガイドを参照してください。

まとめ

ここまでで、Cursor と CircleCI を連携し、次のことができるようになりました。

プッシュ前に設定を検証し、早い段階でエラーを検出する
エディタを離れることなくパイプラインを実行する
ログを探し回る代わりに、自然言語でビルド失敗の原因を特定する
テスト結果を分析し、失敗箇所を迅速に特定・修正する

これはほんの始まりに過ぎません。CircleCI MCP サーバーには、ロールバックやプロジェクトの検出など、さらに多くのツールが用意されています。この連携を日々のワークフローに組み込むことで、コンテキストスイッチに費やす時間を減らし、より多くの時間をコードのリリースに充てられるようになるでしょう。

おわりに

Cursor と CircleCI MCP サーバーを組み合わせることで、CI/CD との関わり方が大きく変わります。パイプラインを開発フローとは別のものとして扱うのではなく、質問する、ビルドを実行する、失敗を修正するといった操作をエディタを離れることなく自然に行えるようになります。

連携のセットアップが完了したら、MCP クックブックでさらに多くの活用例やパターンを参照してみてください。不安定なテストのデバッグ、パイプライン性能の最適化など、実践的なユースケースが多数紹介されています。また、CircleCI MCP サーバーのドキュメントや GitHub リポジトリも、理解を深めるための有用なリソースです。

さっそく試してみませんか？ CircleCI の無料アカウントを作成して、ビルドを始めましょう。

Site

ブログ