cypress-mcp

MCP server that gives AI coding agents full control over Cypress test execution.

Run, debug, and iterate on E2E tests directly from Claude Code, Cursor, Windsurf, or any MCP-compatible agent — without switching to a terminal.

Install

Package Manager	Command
npx (no install)	npx cypress-mcp --cwd /path/to/project
npm	npm install -g cypress-mcp
pnpm	pnpm add -g cypress-mcp
yarn	yarn global add cypress-mcp
bun	bun add -g cypress-mcp
From GitHub	npx github:jams4code/cypress-mcp

Quick Start

Register with your MCP client:

Claude Code:

claude mcp add cypress-mcp -- npx cypress-mcp --cwd /path/to/project

Cursor / VS Code:

{
  "mcpServers": {
    "cypress": {
      "command": "npx",
      "args": ["cypress-mcp", "--cwd", "/path/to/your/project"]
    }
  }
}

Windsurf:

{
  "mcpServers": {
    "cypress": {
      "command": "npx",
      "args": ["cypress-mcp", "--cwd", "/path/to/your/project"]
    }
  }
}

Why

AI agents can write Cypress tests but can't run them. Every change requires you to switch to terminal, run npx cypress run, wait, copy the output back. This kills iteration speed.

cypress-mcp closes the loop. The agent runs specs, reads failures, views screenshots, inspects crash context, reruns the last command, and discovers the test suite — all within the conversation.

Tools (11)

Core Loop

Tool	What it does
cypress_run_spec	Run a spec file headless, get structured JSON results
cypress_run_test	Run a single test by name (grep filter)
cypress_rerun_last	Replay the exact last run without rebuilding arguments
cypress_list_specs	List all spec files with test counts

Debug

Tool	What it does
cypress_get_failure_context	Compact debugging bundle: error, stack, spec excerpt, screenshots, next actions
cypress_get_screenshot	Find failure screenshots by spec or test name
cypress_get_last_run	Full results of the most recent run

Discovery

Tool	What it does
cypress_discover	Map the entire test suite: specs, test names, counts
cypress_analyze_spec	Deep-parse a spec: describe blocks, visits, intercepts, fixtures

Setup

Tool	What it does
cypress_get_env	Show cypress.env.json (secrets masked)
cypress_doctor	Health check: config, binary, specs, support file, directories

How It Works

graph LR
    A[AI Agent] -->|stdio JSON-RPC| B[cypress-mcp]
    B -->|child_process.spawn| C[Cypress Runtime]
    C -->|JSON reporter| B
    B -->|structured result| A

    style A fill:#1a1a2e,stroke:#e94560,color:#fff
    style B fill:#16213e,stroke:#0f3460,color:#fff
    style C fill:#0f3460,stroke:#533483,color:#fff

• stdio transport — the agent spawns the server as a child process
• Serial execution — one Cypress run at a time, no concurrency
• Structured output — JSON results with failure details, diffs, screenshot paths
• Config-aware — auto-detects cypress.config.*, follows relative imports, respects custom paths
• Cross-platform — Windows, macOS, Linux

Agent Workflow

graph TD
    D[cypress_discover] -->|map test suite| E[cypress_analyze_spec]
    E -->|understand spec| F[cypress_run_spec]
    F -->|tests fail| G[cypress_get_failure_context]
    G -->|error + excerpt + screenshots| H[Fix the code]
    H -->|iterate| I[cypress_rerun_last]
    I -->|still failing| G
    I -->|passing| J[Done]
    F -->|tests pass| J

    style D fill:#1a1a2e,stroke:#e94560,color:#fff
    style F fill:#16213e,stroke:#0f3460,color:#fff
    style G fill:#e94560,stroke:#fff,color:#fff
    style I fill:#0f3460,stroke:#533483,color:#fff
    style J fill:#2d6a4f,stroke:#40916c,color:#fff

Configuration

Works out of the box for standard Cypress projects. For custom setups, create cypress-mcp.config.json:

{
  "defaultBrowser": "chrome",
  "defaultTimeout": 600000,
  "cypressConfigFile": "config/cypress.config.ts",
  "specPattern": ["e2e/**/*.cy.ts"],
  "supportFile": "support/e2e.ts",
  "titleFilterSupport": true,
  "screenshotsDir": "cypress/screenshots"
}

Supported Versions

• Cypress 12.x — 15.x
• Node.js 18+
• Windows, macOS, Linux

Registry Status

Registry	Package	Status
npm	cypress-mcp	Published
GitHub	jams4code/cypress-mcp	Source

Development

git clone https://github.com/jams4code/cypress-mcp.git
cd cypress-mcp
npm install
npm run build
npm test

License

Business Source License 1.1 — free for individuals, education, and open source. Commercial production use requires a license. See LICENSING.md for details.

Converts to Apache 2.0 on March 25, 2029.

Licensed by JADEV GROUP SARL (BE1027.114.687), Brussels, Belgium.