Cypress Mcp

io.github.miroslavmyrhaPublished by GitHub account miroslavmyrhav0.1.2Updated Oct 24, 2026

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

The publisher's own server: Cypress Cloud MCP

VerifiedSTDIODesktop onlyDeveloper ToolsSecurity & Monitoring

Overview

AI-generated overview

Lets an AI assistant inspect the last Cypress test run: command log, errors, screenshots, and the DOM of failed tests.

What you can do
It reads the results of the last cypress run so the assistant can see which commands each test ran, the failure error, a screenshot, and the DOM snapshot at the moment of failure. Tools include list_specs, read_spec, get_config, get_last_run, get_screenshot, query_dom, and run_spec, which runs a single spec and waits for completion.
When to use it
Use it when Cypress tests run headless on your machine or in CI and the assistant should see why one failed. For debugging while writing tests in the open Cypress app, the official cypress tap fits better.
Requirements
Needs Node.js 18+ and Cypress 12+, plus registering the plugin in cypress.config and importing the support module. Installed as the npm package @miroslavmyrha/cypress-mcp and connected over stdio or HTTP; HTTP mode can set MCP_HTTP_TOKEN.
Before you install
run_spec actually executes tests, which can trigger side effects in the tested application. get_config reads the config file with secret-looking values redacted; in HTTP mode without MCP_HTTP_TOKEN a random token is generated and printed to stderr. DOM snapshots and screenshots are written under the project's .cypress-mcp directory, which should be gitignored.

Installation

In SourceWeft

  1. Open Cypress Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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

Source: README.md at commit f6b9153

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.2LatestOct 13, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Cypress integrations

Cypress Cloud MCP

io.cypress.mcpOfficial publisher

Remote Cypress Cloud MCP server that gives AI assistants access to your Cypress test results and accessibility reports.

Streamable HTTPWeb executableAuth
Developer ToolsCredential requiredNov 2, 2026