Cypress CloudのMCPをClaude Codeで使う方法

Cypress Cloud MCPは、CypressのSaaS版であるCypress CloudのMCPサーバーです。2026年5月20日に正式リリースされ、Starterプランを含む全プランで追加費用なしに使えます。Claude Codeから「このブランチの最新実行結果を教えて」と聞くだけで、CIとエディタの間を人手で行き来せずにテスト失敗の調査が進みます。

一方で、公式MCPが提供されているのはCypress Cloud側だけです。OSSのテストランナー本体(cypress runでテストを実行する側)に公式MCPはまだなく、Cypress側はまずエージェント向けCLIから始める方針を示しています。

Cypress Cloud MCPとは何ができるか

Cypress Cloud MCPは、Cypress Cloudに蓄積されたテスト実行結果をAIエージェントから直接照会できるようにするリモートMCPサーバーです。実行ステータスの確認、フレーキーテストの特定、失敗の詳細(Test Replayへのリンクを含む)の取得を、エージェントが会話の流れの中で自律的に呼び出します。

MCPの仕組みは「AI向けのUSBポート」に例えられます。AIクライアント(Host)がCypress Cloud(Server)にプラグインし、OAuthまたは個人アクセストークン(PAT)で認証された経路(Connection)を通じてリアルタイムのデータを取得します。読み取り専用で、テストコードの変更やRunの削除はできません。

利用にあたって、Cypress App側の最低バージョンは求められません。

導入前の準備 — 組織の有効化と認証方式

利用開始までの流れは3ステップです。

認証方式は2つあります。

OAuthのセッションはCypress CloudのManage Profileページに一覧表示され、そこからいつでも失効できます。PATはCypress Cloudにサインイン後、組織の画像→Manage Profile→MCP personal access tokenのGenerate tokenで発行します。トークンは発行時にしか表示されないため、その場でコピーします。

Claude Codeへの接続手順(claude mcp add)

Cloud MCPはリモートのHTTPサーバーで、URLはhttps://mcp.cypress.io/mcp固定です。OAuth対応クライアントならURLを登録するだけでブラウザ認証が走ります。

claude mcp add cypress-cloud \
  https://mcp.cypress.io/mcp \
  --transport http

追加後、claudeでセッションを開始し、「mcp cypress」のようにCypress Cloudを指す一言をプロンプトに含めると、Claude Codeがブラウザウィンドウを開いてCypress Cloudへのサインインを求めます。

PATを使う場合はヘッダーでトークンを渡します。

claude mcp add cypress-cloud \
  https://mcp.cypress.io/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_MCP_TOKEN"

スコープは--scope user(全プロジェクトで共有、Cypress公式の推奨)・--scope local(既定、現在のプロジェクトのみ)・--scope project(.mcp.jsonでチーム共有)の3種類から選べます。

チーム共有の.mcp.jsonはこう書き出される

v2.1.289で--scope projectを付けて追加すると、作業ディレクトリに次の.mcp.jsonができます。サーバーへの接続は行われず、設定が書き出されるだけです。

claude mcp add cypress-cloud https://mcp.cypress.io/mcp \
  --transport http --scope project

{
  "mcpServers": {
    "cypress-cloud": {
      "type": "http",
      "url": "https://mcp.cypress.io/mcp"
    }
  }
}

PATの--header付きで追加すると、同じファイルのheadersにトークンがそのまま入ります。画面にはAuthorizationの値が[REDACTED]と伏せて表示されますが、ファイルの中身は平文です。このファイルをリポジトリにコミットすると、トークンも一緒に共有されます。共有用はOAuth構成の.mcp.jsonにして、PATは各自のローカルスコープに入れる分け方があります。

同じ名前で再度追加するとエラーになります。

MCP server cypress-cloud already exists in .mcp.json

PATからOAuthへ切り替えるときも、名前が同じなら一度削除してから追加し直します。Claude Code全体のスコープや.mcp.jsonの扱いはClaude Code MCP設定ガイドが詳しいです。

Claude Desktopから使う場合

Claude Desktopでは、Customize→Connectors→+から「Add custom connector」を選び、名前にcypress-cloud、リモートMCPのURLにhttps://mcp.cypress.io/mcpを入れて接続します。PATを使う場合はclaude_desktop_config.jsonにmcp-remote経由で書く方式で、Node.js v22以上がPATHに必要です。

使えるツールとプロンプトの書き方

接続後にエージェントが自律的に呼び出すツールは、Cypress Cloudの公式ページに13個載っています。ユーザーが手で呼ぶのではなく、プロンプトの内容に応じてエージェントが選びます。

cypress_get_failed_testsはテストの成果物(スクリーンショットなど)を返しません。成果物まで欲しいときはCloud CLIの出番です。また、フレーキーテストの検出やアクセシビリティ・UI Coverageのレポートは、その機能を契約している組織にだけ元データがあります。契約していないプランやプロダクトの元データは、該当ツールからは得られません。

応答は意図的にコンパクトに作られ、トークンとコンテキストの消費を抑えます。詳細が必要な問いには、エージェントが追加でツールを呼んで掘り下げます。

効果的なプロンプトには4つの原則があります。①「Cypress Cloud」と明示して正しいツールを呼ばせる。②「このブランチ」「このコミット」やRun URLを直接貼って文脈を渡す。③ランやブランチなど必要な範囲だけを頼み、応答を小さく保つ。④「何が落ちたか」だけでなく「直して」まで指示に含める。使用回数には全プラン共通で1時間あたり100リクエストの上限があり、上げたい場合はCypressのサポートに連絡します。

ブランチ名だけを渡して調査からスタートさせる例です。

Check Cypress Cloud for the latest run on this branch.
Give me a high-level summary of any failures.

これだけで、該当ブランチの最新Run取得(cypress_get_runs)から失敗テストの詳細取得(cypress_get_failed_tests)まで、エージェントが必要なツールを自分で選んで実行します。

失敗の調査から修正までつなげたいときは、ローカルのコードを読ませる一言を足します。

Find the failing tests for [Run URL]. For each failure, look at the
stack trace, check my local code, and propose a fix to stop the regression.

失敗の調査以外にも、公式ページには次のような使い方が例示されています。

• 直近5回のRunからフレーキーテストを列挙し、エラーメッセージに共通パターンがあるか尋ねる
• mainの最新Runについて、コミットの作者・ステータス・実行スペック・スキップされたテストを並べたリリースレポートを作らせる
• Run内のスペックを所要時間順に並べ、最も遅いスペックをテスト単位に分解して、分割すべきか判断する材料にする
• skippedとpendingのテストをスペック別に並べ、実行されなくなったテストの増加を点検する

Cloud MCPとCloud CLIの使い分け

Cypress Cloudには、プログラムからのアクセス手段がもう1つあります。ターミナルで使うcy-cloud(Cloud CLI)です。どちらも同じCypress Cloudのデータに触り、全プラン無料で使えます。

Cloud CLIの導入には、Cypress Cloudの組織でCloud CLIを有効にし、Node.js 22.21.0以上でnpmパッケージを入れます。

npm install --global @cypress/cloud
cy-cloud --help
cy-cloud login

cy-cloud loginはOAuthでのサインインで、CIではトークンを環境変数で渡す使い方が案内されています。コマンドはrun list・test get・replay timelineのように分かれています。Cloud MCPを繋いだClaude Codeでも、ターミナルを使うエージェントとしてCloud CLIを併用できます。

セキュリティ — Cypressが見えるもの・見えないもの

Cloud MCPはAIエージェント向けのAPIとして動作し、アプリケーションがAPIを呼ぶのと同じ形でしかCypress側にデータは渡りません。Cypressが受け取るのはgetRuns(projectId: 100, runNumber: 45, limit: 10)のようなツール呼び出しの引数だけで、AIとのチャット履歴やコンテキストウィンドウの中身には一切アクセスできません。テスト結果やスタックトレース、Replayリンクはリクエストに答える目的にのみ使われ、LLMの学習データにも使われません。

権限面では、Cloud MCPは読み取り専用でテストコードの変更やRunの削除はできません。各ユーザーは自分のCypress Cloudアカウントが持つ権限の範囲でしかデータにアクセスできません。データの保持期間は、プランごとのテスト記録の上限と保持ポリシーに従います。

組織側はIntegrationsページのCypress MCP欄でDisableを選べば、いつでも統合を止められます。無効化した瞬間に、OAuth・PATを問わず組織内の全ユーザーのアクセスが失効します。

公式MCPはCloud限定 — テストランナー本体にはまだ無い

Cypress Cloud MCPが公式に存在する一方、cypress runを実行するOSSのテストランナー本体を対象にした公式MCPは存在しません。Cypressのリポジトリには2026年2月25日に「Proposal: Official MCP server for Cypress(@cypress/mcp)」というIssueが立ち、9件のコメントを集めています。2026年6月にはCypressのメンバーが、まずエージェント向けCLIから始める方針をコメントで示しており、公式MCPは公開されていません。

提案されている構想では、cypress_run(スペック実行と結果取得)、cypress_write_spec(テストファイルの生成)、cypress_snapshot(ページのARIAツリー取得)のようなツールでテストの生成・実行・デバッグをAIに任せる形が想定されています。提案では、Playwrightチームの@playwright/mcpが比較対象に挙げられています。

つまり、実行結果の照会と分析はCloud MCP、テストの実行・記述そのものはClaude Codeのシェル実行やコマンド呼び出しという役割分担になります。既存のCI連携にCypress Cloudを使っているチームであれば、Cloud MCP単体でも「落ちたテストの原因を聞く」という主要なユースケースはカバーできます。同じテスト自動化ツールのMCP化ではPlaywright MCPサーバーの使い方が、ブラウザ操作そのものをAIに任せる選択肢になります。

よくあるつまずき

エージェントがRunを見つけられない。組織でCloud MCP統合が有効になっているか、CIで記録されたGitブランチ名とエージェントに伝えたブランチ名が一致しているかを確認します。CIジョブが赤(失敗)で終わっていても、Cypress自体がRunを記録していればCloud上にデータは残ります。赤はジョブの終了コードを反映しているだけなので、ブランチ名・コミット・Run番号・Run URLで直接問い合わせます。

CIやGitHubのMCPでジョブログを読ませている場合、Run URLはCypress CLIの出力の末尾近くに出ます。エージェントにログの末尾を読ませると、リンクを見落とさずに済みます。

OAuthのブラウザ認証が開かない。https://cloud.cypress.ioにブラウザから到達できるか、ファイアウォールやプロキシがhttps://mcp.cypress.ioを許可しているかを確認します。改善しない場合は、AIクライアント側のMCP設定を一度削除して再登録します。PATを使っている場合は、Manage Profile画面でトークンの有効期限が切れていないかも合わせて確認します。

PATからOAuthへの切り替え。AIクライアントの設定からAuthorizationヘッダーやトークンの環境変数を削除して保存するだけで、次回接続時にOAuthのブラウザサインインへ自動的に切り替わります。Claude Codeでの入れ直しは前述のとおり、削除してから再追加します。

まとめ

まず試すなら、OAuthでURLを1行登録し、「Cypress Cloudの最新Runの失敗を要約して」と聞くところからです。テストランナー本体の操作はまだMCPで任せられないため、実行はこれまでどおりシェルで行い、Cloudの結果照会だけをMCPに寄せる分担になります。