Skip to main content
Glama
miroslavmyrha

cypress-mcp

by miroslavmyrha
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

cypress-mcp

MCP server that connects Claude to your Cypress test runner. Claude can read your spec files and see exactly what happened in the last test run — which commands ran, what failed, error messages, and DOM snapshots.

How it works

cypress open → test runs in browser
  → 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

Related MCP server: cypress-mcp

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 — 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 — 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 — .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+

Author

Miroslav Myrha

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers