Skip to main content
Glama
Sign In
cypress-mcp

cypress-mcp

by miroslavmyrha
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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.

npm install -D @miroslavmyrha/cypress-mcp

Example

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

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):

{
  "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:

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

Related MCP server: cypress-mcp

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 package

cypress tap

Cypress Cloud MCP

Reads

the last local cypress run

a live cypress open session

runs recorded to Cypress Cloud

Headless runs and CI

yes

no

only what was recorded

Command log and DOM of a failed test

yes

yes

no, links to Test Replay

Needs

Cypress 12 or newer, a plugin and a support import

Cypress 15.21 or newer, a Chromium browser

a Cypress Cloud account

Interface

MCP (stdio or HTTP)

command line

MCP

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

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

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

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):

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

Or with claude mcp add:

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

4b. HTTP transport (Ollama, custom bridges)

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

Tool

Description

list_specs

List all Cypress spec files. Optional pattern glob (default: **/*.cy.{ts,js,tsx,jsx})

read_spec

Read a spec file's content by relative path

get_config

Read the Cypress config file (cypress.config.ts/js/mjs/cjs), secret-looking values redacted

get_last_run

Get results of the last test run: states, errors, command log, DOM snapshots

get_screenshot

Get a screenshot from the last run. Returns the image itself (up to 2 MB) plus path and size metadata

query_dom

Query the DOM snapshot of a failed test using a CSS selector

run_spec

Run a single Cypress spec file and wait for completion. Returns exit code and summary

Output format of .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": "test@example.com" }
          ],
          "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

.cypress-mcp/

Environment variables

Variable

Description

MCP_HTTP_TOKEN

Set 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:

bun install
bun run typecheck
bun run test
bun run build

Requirements

  • Node.js 18+

  • Cypress 12+ (developed and tested with Cypress 13)

Author

Miroslav Myrha

License

MIT

This server cannot be deployed

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • cypress-mcp

    jams4code
    A
    license
    A
    quality
    C
    maintenance
    MCP server that gives AI coding agents full control over Cypress test execution, allowing them to run, debug, and iterate on E2E tests directly from MCP-compatible agents.
    11
    1,198 npm
    1
    Apache 2.0

  • Glance

    Phuong26841
    A
    license
    Not graded
    quality
    A
    maintenance
    An MCP server that gives Claude Code a real browser to navigate, click, type, screenshot, and inspect pages via accessibility snapshots. It also runs multi-step test scenarios with assertions, session recording, visual regression, and console/network monitoring from the terminal.
    106 npm
    MIT

  • Glance

    SzymonLeclerc51
    A
    license
    Not graded
    quality
    B
    maintenance
    An MCP server that gives Claude Code control of a real browser, letting it navigate pages, click and type, capture screenshots, read accessibility snapshots, and run multi-step test scenarios with assertions. It also supports session recording, visual regression comparison, and network/console monitoring with configurable security profiles.
    106 npm
    MIT