cypress-mcp

cypress-mcp

AI アシスタントに、直近の cypress run で何が起きたかを示す MCP サーバーです。各テストで実行されたコマンド、失敗した内容、エラー、スクリーンショット、失敗した瞬間のページの状態を確認できます。

お使いのマシンや CI でのヘッドレス実行向けに作られています。公式ツールではカバーされない状況です。詳しくは比較をご覧ください。

npm install -D @miroslavmyrha/cypress-mcp

例

3 つのテストがある仕様ファイルです。最後のテストは失敗します。

it('shows a counter of finished items', () => {
  cy.get('.todo-list li').first().find('input[type=checkbox]').check()
  cy.get('[data-test=finished-count]').should('contain', '1')
})

cypress run の後、アシスタントが get_last_run を呼び出すと、実行されたコマンド、エラー、DOM スナップショットのパスを取得します（出力は省略しています）。

{
  "title": "Todo list > shows a counter of finished items",
  "state": "failed",
  "domSnapshotPath": "snapshots/cypress-e2e-todo-cy-js/todo-list-shows-a-counter-of-finished-items-d963bb8d.html",
  "commands": [
    { "name": "visit", "message": "https://example.cypress.io/todo" },
    { "name": "get", "message": ".todo-list li" },
    { "name": "first", "message": "" },
    { "name": "find", "message": "input[type=checkbox]" },
    { "name": "check", "message": "" },
    { "name": "get", "message": "[data-test=finished-count]" }
  ],
  "error": "AssertionError: Timed out retrying after 2000ms: Expected to find element: `[data-test=finished-count]`, but never found it."
}

その後、テスト失敗時点のページを確認できます。セレクター .todo-count を指定した query_dom の結果です。

{
  "selector": ".todo-count",
  "totalMatches": 1,
  "results": [
    {
      "breadcrumb": "body > section.todoapp-wrapper > div.todoapp > footer.footer > span.todo-count",
      "outerHTML": "<span class=\"todo-count\"><strong>1</strong> item left</span>"
    }
  ]
}

カウンターは別のセレクターの下に存在することが分かります。ログをチャットに貼り付けなくても、アシスタントはテストを修正できます。

仕組み

cypress run → tests run
  → support/index.ts captures Cypress command log per test
  → cy.task('mcpSaveTestLog') transfers logs to node side
  → plugin/index.ts stores logs in memory
  → after:spec → merges logs + results → writes .cypress-mcp/last-run.json

Claude → MCP server → get_last_run → reads last-run.json

比較

Cypress には AI アシスタント向けのツールが 2 つあります。それぞれ、このパッケージとは異なる状況を対象としています。

	このパッケージ	cypress tap	Cypress Cloud MCP
読み取るもの	直近のローカルな cypress run	実行中の cypress open セッション	Cypress Cloud に記録された実行
ヘッドレス実行と CI	対応	非対応	記録されたもののみ
失敗したテストのコマンドログと DOM	対応	対応	非対応。Test Replay へのリンクを表示
必要なもの	Cypress 12 以降、プラグイン、support のインポート	Cypress 15.21 以降、Chromium ブラウザー	Cypress Cloud アカウント
インターフェース	MCP（stdio または HTTP）	コマンドライン	MCP

Cypress アプリを開いてテストを作成するときは、cypress tap を使います。テストがヘッドレスで実行され、失敗した理由をアシスタントに確認させたい場合は、このパッケージを使います。

結果は、Cypress が実行モードで発火する after:spec イベントに書き込まれます。cypress open では、このイベントに experimentalInteractiveRunEvents が必要です。

アシスタントに渡る前に、シークレットらしき値はマスキングされ、テスト対象アプリケーションから取得したコンテンツは信頼できないデータとしてマークされます。

セットアップ

1. インストール

npm install -D @miroslavmyrha/cypress-mcp

注：npm にあるスコープなしの cypress-mcp は、無関係なプロジェクトが所有しています。必ずスコープ付きの @miroslavmyrha/cypress-mcp を使用してください。

2. cypress.config.ts にプラグインを登録する

import { defineConfig } from 'cypress'
import { cypressMcpPlugin } from '@miroslavmyrha/cypress-mcp/plugin'

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      cypressMcpPlugin(on, config)
    },
  },
})

3. cypress/support/e2e.ts で support をインポートする

import '@miroslavmyrha/cypress-mcp/support'

4a. Claude Desktop / Claude Code を設定する（stdio トランスポート）

MCP 設定（~/.config/claude/claude_desktop_config.json または claude mcp add）に追加します。

{
  "mcpServers": {
    "cypress": {
      "command": "npx",
      "args": ["-y", "@miroslavmyrha/cypress-mcp", "--project", "/absolute/path/to/your/project"]
    }
  }
}

または、claude mcp add を使用します。

claude mcp add cypress -- npx -y @miroslavmyrha/cypress-mcp --project /absolute/path/to/your/project

4b. HTTP トランスポート（Ollama、カスタムブリッジ）

# Start MCP server in HTTP mode (random token printed to stderr)
npx -y @miroslavmyrha/cypress-mcp --project /path/to/project --transport http --port 3333

# Or with a fixed token for automated deployments
MCP_HTTP_TOKEN=$(openssl rand -hex 32) npx -y @miroslavmyrha/cypress-mcp --project /path/to/project --transport http --port 3333

# Server listens on:
#   POST http://localhost:3333/mcp  → tool calls (MCP Streamable HTTP)

MCP ツール

ツール	説明
list_specs	すべての Cypress 仕様ファイルを一覧表示します。省略可能な pattern glob（デフォルト：**/*.cy.{ts,js,tsx,jsx}）
read_spec	相対パスで指定した仕様ファイルの内容を読み取ります
get_config	Cypress 設定ファイル（cypress.config.ts/js/mjs/cjs）を読み取ります。シークレットらしき値はマスキングされます
get_last_run	直近のテスト実行結果（状態、エラー、コマンドログ、DOM スナップショット）を取得します
get_screenshot	直近の実行からスクリーンショットを取得します。画像本体（最大 2 MB）とパスおよびサイズのメタデータを返します
query_dom	CSS セレクターを使って、失敗したテストの DOM スナップショットを検索します
run_spec	Cypress の仕様ファイルを 1 つ実行し、完了まで待機します。終了コードと概要を返します

.cypress-mcp/last-run.json の出力形式

{
  "timestamp": "2026-02-18T22:00:00Z",
  "specs": [
    {
      "spec": "cypress/e2e/login.cy.ts",
      "stats": { "passes": 3, "failures": 1, "pending": 0, "skipped": 0, "duration": 5230 },
      "screenshots": ["/abs/path/to/Login -- should show error (failed).png"],
      "tests": [
        {
          "title": "Login > should login with valid credentials",
          "state": "passed",
          "duration": 1200,
          "error": null,
          "domSnapshotPath": null,
          "commands": [
            { "name": "visit", "message": "/login" },
            { "name": "get", "message": "#email" },
            { "name": "type", "message": "[email protected]" }
          ],
          "consoleErrors": [],
          "networkErrors": []
        },
        {
          "title": "Login > should show error on invalid password",
          "state": "failed",
          "duration": 800,
          "error": "Timed out retrying: Expected to find element: .error-message",
          "domSnapshotPath": "snapshots/cypress-e2e-login-cy-ts/login--should-show-error-a1b2c3.html",
          "commands": [...],
          "consoleErrors": ["Uncaught TypeError: Cannot read property 'x' of null"],
          "networkErrors": [{ "method": "POST", "url": "/api/login", "status": 500 }]
        }
      ]
    },
    {
      "spec": "cypress/e2e/dashboard.cy.ts",
      "stats": { ... },
      "screenshots": [],
      "tests": [...]
    }
  ]
}

実行時のすべての spec が記録されます。cypress run では、before:run の時点で累積データがリセットされます。cypress open では、Cypress プロセスが動作している間、結果が累積されます。失敗したテストには、.cypress-mcp/snapshots/ に保存された HTML ファイル（document.body.outerHTML の最大 100 KB）を指す domSnapshotPath が含まれます。

CLI オプション

Options:
  --project <path>     Cypress project root (default: current directory)
  --transport <type>   stdio or http (default: stdio)
  --port <number>      HTTP port, only for --transport http (default: 3333)
  -V, --version        Show version
  -h, --help           Show help

.cypress-mcp を .gitignore に追加する

.cypress-mcp/

環境変数

変数	説明
MCP_HTTP_TOKEN	HTTP トランスポート用の固定ベアラートークンを設定します（32 文字以上）。設定されていない場合、起動のたびにランダムなトークンが生成され、stderr に出力されます。

開発

このプロジェクトでは、パッケージマネージャーとして Bun を使用します。

bun install
bun run typecheck
bun run test
bun run build

要件

• Node.js 18 以降
• Cypress 12 以降（Cypress 13 で開発およびテスト済み）

作成者

Miroslav Myrha

ライセンス

MIT