Cypress Mcp

io.github.miroslavmyrha由 GitHub 帳號 miroslavmyrha 發布v0.1.2更新於 Oct 24, 2026

Shows an AI assistant the last cypress run: command log, errors, screenshots, DOM of failed tests.

發布方自己的服務：Cypress Cloud MCP

已驗證STDIO僅桌面開發者工具安全與監控

概覽

AI 產生的概覽

讓 AI 助理查看最近一次 Cypress 測試執行的指令記錄、錯誤、截圖與失敗測試的 DOM。

可以做什麼
它讀取最近一次 cypress run 的結果，讓助理看到每個測試執行了哪些指令、失敗的錯誤訊息、截圖，以及失敗當下的 DOM 快照。工具包含 list_specs、read_spec、get_config、get_last_run、get_screenshot、query_dom 與 run_spec，其中 run_spec 可執行單一 spec 並等待完成。
適用情境
當 Cypress 測試以 headless 模式在本機或 CI 執行，而你希望助理直接看到失敗原因時使用。若你是在開啟的 Cypress 應用程式中邊寫測試邊除錯，官方 cypress tap 更合適。
執行需求
需 Node.js 18+ 與 Cypress 12+，並在 cypress.config 註冊外掛、在 support 檔案匯入支援模組。以 npm 套件 @miroslavmyrha/cypress-mcp 安裝，透過 stdio 或 HTTP 連線；HTTP 模式可設定 MCP_HTTP_TOKEN。
安裝前請注意
run_spec 會實際執行測試，可能觸發受測應用程式的副作用。get_config 會讀取設定檔，敏感值會遮蔽；HTTP 模式若未設定 MCP_HTTP_TOKEN，會產生隨機權杖並輸出到 stderr。DOM 快照與截圖會寫入專案的 .cypress-mcp 目錄，建議加入 .gitignore。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Cypress Mcp，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

cypress-mcp

[npm] [CI] [License: MIT]

MCP server that shows an AI assistant what happened in your last cypress run: which commands each test ran, what failed, the error, a screenshot, and the page as it was at the moment of the failure.

It is made for headless runs, on your machine and in CI. That is the place the official tools do not reach, see How it compares.

bash
npm install -D @miroslavmyrha/cypress-mcp

Example

A spec with three tests, the last of which fails:

js
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')})

After cypress run, the assistant calls get_last_run and gets the commands that ran, the error and the path of a DOM snapshot (output shortened):

json
{  "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."}

It can then look into the page as it was when the test failed. query_dom with the selector .todo-count:

json
{  "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>"    }  ]}

So the counter exists, under another selector, and the assistant can fix the test without anyone pasting logs into the chat.

How it works

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

How it compares

Cypress has two tools of its own for AI assistants. They cover other situations than this one.

this packagecypress tapCypress Cloud MCP
Readsthe last local cypress runa live cypress open sessionruns recorded to Cypress Cloud
Headless runs and CIyesnoonly what was recorded
Command log and DOM of a failed testyesyesno, links to Test Replay
NeedsCypress 12 or newer, a plugin and a support importCypress 15.21 or newer, a Chromium browsera Cypress Cloud account
InterfaceMCP (stdio or HTTP)command lineMCP

Use cypress tap while you write a test with the Cypress app open. Use this package when the tests run headless and the assistant should see why one failed.

The results are written in the after:spec event, which Cypress fires in run mode. In cypress open that event needs experimentalInteractiveRunEvents.

Before anything reaches the assistant, values that look like secrets are redacted, and content that comes from the tested application is marked as untrusted data.

Setup

1. Install

bash
npm install -D @miroslavmyrha/cypress-mcp

Note: the unscoped cypress-mcp name on npm belongs to an unrelated project. Always use the scoped @miroslavmyrha/cypress-mcp.

2. Register the plugin in cypress.config.ts

typescript
import { defineConfig } from 'cypress'import { cypressMcpPlugin } from '@miroslavmyrha/cypress-mcp/plugin'
export default defineConfig({  e2e: {    setupNodeEvents(on, config) {      cypressMcpPlugin(on, config)    },  },})

3. Import support in cypress/support/e2e.ts

typescript
import '@miroslavmyrha/cypress-mcp/support'

4a. Configure Claude Desktop / Claude Code (stdio transport)

In your MCP settings (~/.config/claude/claude_desktop_config.json or claude mcp add):

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

Or with claude mcp add:

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

4b. HTTP transport (Ollama, custom bridges)

bash
# 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 deploymentsMCP_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 Tools

ToolDescription
list_specsList all Cypress spec files. Optional pattern glob (default: **/*.cy.{ts,js,tsx,jsx})
read_specRead a spec file's content by relative path
get_configRead the Cypress config file (cypress.config.ts/js/mjs/cjs), secret-looking values redacted
get_last_runGet results of the last test run: states, errors, command log, DOM snapshots
get_screenshotGet a screenshot from the last run. Returns the image itself (up to 2 MB) plus path and size metadata
query_domQuery the DOM snapshot of a failed test using a CSS selector
run_specRun a single Cypress spec file and wait for completion. Returns exit code and summary

Output format of .cypress-mcp/last-run.json

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

All specs from a run are captured. In cypress run the accumulator resets on before:run. In cypress open results accumulate for the lifetime of the Cypress process. Failed tests include a domSnapshotPath pointing to an HTML file (up to 100 KB of document.body.outerHTML) stored under .cypress-mcp/snapshots/.

CLI options

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

Add .cypress-mcp to .gitignore

gitignore
.cypress-mcp/

Environment variables

VariableDescription
MCP_HTTP_TOKENSet a fixed bearer token for HTTP transport (min 32 chars). If not set, a random token is generated on each start and printed to stderr.

Development

This project uses Bun as the package manager:

bash
bun installbun run typecheckbun run testbun run build

Requirements

  • Node.js 18+
  • Cypress 12+ (developed and tested with Cypress 13)

Author

Miroslav Myrha

License

MIT

來源：README.md，提交 f6b9153

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

1
  1. v0.1.2最新Oct 13, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分

其他 Cypress 整合

Cypress Cloud MCP

io.cypress.mcp官方發布者

遠端 Cypress Cloud MCP 伺服器，讓 AI 助理存取你的 Cypress 測試結果與無障礙報告。

Streamable HTTP可網頁執行驗證方式
開發者工具需要憑證Nov 2, 2026