cypress-mcp

MCP (Model Context Protocol) server plugin for Cypress — let AI agents control your browser for testing.

Turn Cypress into an MCP server that AI clients (Claude Desktop, Cursor, Windsurf, etc.) can use to navigate, interact with, and test web applications.

Features

• 52 browser automation tools — navigate, click, type, screenshot, intercept network, iframes, and more

• Accessibility-first DOM snapshots — ARIA-based page representation optimized for LLM understanding

• Zero config — just 2 lines to integrate into your Cypress project

• Network interception — capture, filter, and mock HTTP requests

• Test generation — automatically generate Cypress tests from recorded sessions

• Plugin system — extend with custom tools via third-party plugins

• MCP standard — works with any MCP-compatible AI client

Quick Start

Install

npm install cypress-mcp --save-dev

Configure (2 lines)

cypress.config.ts:

import { defineConfig } from 'cypress';
import { cypressMcp } from 'cypress-mcp/plugin';

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000', // your app
    setupNodeEvents(on, config) {
      cypressMcp(on, config);
      return config;
    },
  },
});

cypress/support/e2e.ts:

import 'cypress-mcp/support';

Run

# Auto-detects baseUrl from cypress.config
npx cypress-mcp

# Or override baseUrl for a specific project
npx cypress-mcp --base-url http://localhost:4200

# All options
npx cypress-mcp --base-url http://localhost:3000 --browser chrome --port 3457 --debug

Connect to MCP Clients

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "cypress": {
      "command": "npx",
      "args": ["cypress-mcp"]
    }
  }
}

baseUrl is auto-detected from cypress.config.ts in the working directory. To override:

{
  "mcpServers": {
    "cypress": {
      "command": "npx",
      "args": ["cypress-mcp", "--base-url", "http://localhost:4200"],
      "env": {
        "CYPRESS_BASE_URL": "http://localhost:4200"
      }
    }
  }
}

VS Code / Cursor:

{
  "mcpServers": {
    "cypress": {
      "command": "npx",
      "args": ["cypress-mcp", "--base-url", "http://localhost:3000"]
    }
  }
}

Claude Code:

claude mcp add cypress npx cypress-mcp --base-url http://localhost:3000

baseUrl Resolution Order

The CLI resolves baseUrl from multiple sources (highest priority first):

1. --base-url CLI argument

2. CYPRESS_BASE_URL environment variable

3. Auto-detected from cypress.config.{ts,js} in current directory

4. No baseUrl (Cypress works without it — use browser_navigate to go anywhere)

Tools (38 total)

Navigation (4)

Interaction (9)

Snapshot & DOM (4)

Network (5)

Screenshot & Visual (2)

Console & Debug (2)

Tab Management (4)

Storage & Cookies (5)

Dialog (1)

Utility (4)

Architecture

┌─────────────────┐    stdio/SSE     ┌─────────────────┐
│   AI Client     │ ◄──────────────► │   MCP Server    │
│ (Claude, etc.)  │                  │   (Node.js)     │
└─────────────────┘                  │                 │
                                     │  38 Tool        │
                                     │  Handlers       │
                                     │                 │
                                     │  State Manager  │
                                     └────────┬────────┘
                                              │ cy.task()
                                              │ (polling)
                                     ┌────────┴────────┐
                                     │  Cypress Browser │
                                     │                 │
                                     │  Agent Loop     │
                                     │  DOM Snapshotter│
                                     │  Net Interceptor│
                                     │  Console Hook   │
                                     └─────────────────┘

3-Layer Architecture:

1. MCP Server (Node.js) — Handles MCP protocol, tool registration, request routing

2. Bridge — cy.task() based polling between Node.js and Cypress browser

3. Cypress Runtime — Agent spec keeps browser open, executes commands, captures state

Options

cypressMcp(on, config, {
  wsPort: 3456,        // Bridge port
  transport: 'stdio',  // 'stdio' or 'sse'
  ssePort: 3100,       // SSE port (if transport === 'sse')
  debug: false,        // Debug logging
});

How it Works

1. cypressMcp() starts an MCP server (stdio) and registers 38 tool handlers

2. Cypress runs an "agent spec" that keeps the browser open in a polling loop

3. When the AI client calls a tool (e.g., browser_navigate), the MCP server queues a command

4. The browser-side agent polls for commands via cy.task('mcpBridgePoll')

5. Commands execute as real Cypress commands (cy.visit, cy.click, etc.)

6. Results flow back through cy.task('mcpBridgeResponse')

Security

See SECURITY.md for security considerations, especially regarding browser_evaluate and browser_run_cypress tools.

Important: This tool is for development/testing only. Do not expose the MCP server to untrusted networks.

Requirements

• Node.js >= 18

• Cypress >= 12.0.0

License

MIT