cypress-mcp

cypress-mcp

一个 MCP 服务，可向 AI 助手展示上次 cypress run 的运行情况：每个测试运行了哪些命令、哪里失败、错误信息、截图，以及失败那一刻的页面状态。

它适用于在本机和 CI 中进行无头运行。这正是官方工具无法覆盖的场景，详见对比。

npm install -D @miroslavmyrha/cypress-mcp

示例

一个包含三个测试的 spec，其中最后一个测试失败：

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 助手的自有工具。它们适用于不同的场景。

	此软件包	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。当测试以无头模式运行，且助手需要了解失败原因时，请使用此软件包。

结果会在 after:spec 事件中写入，Cypress 在运行模式下会触发此事件。在 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 spec 文件。可选的 pattern glob（默认值：**/*.cy.{ts,js,tsx,jsx}）
read_spec	根据相对路径读取 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 spec 文件并等待完成。返回退出代码和摘要

.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": [...]
    }
  ]
}

运行中的所有测试规格都会被记录。在 cypress run 中，累积器会在 before:run 时重置。在 cypress open 中，结果会在整个 Cypress 进程运行期间累积。失败的测试会包含一个 domSnapshotPath，指向存储在 .cypress-mcp/snapshots/ 下的 HTML 文件（最多包含 100 KB 的 document.body.outerHTML）。

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 传输设置固定的 bearer token（至少 32 个字符）。如果未设置，每次启动时都会生成一个随机 token，并打印到 stderr。

开发

本项目使用 Bun 作为包管理器：

bun install
bun run typecheck
bun run test
bun run build

要求

• Node.js 18+
• Cypress 12+（使用 Cypress 13 开发并测试）

作者

Miroslav Myrha

许可证

MIT