cypress-mcp

MCP server for Cypress — let AI agents run tests, manage specs, snapshot pages, and automate browsers.

npm version License: MIT Tested with Vitest

What is this?

cypress-mcp is a Model Context Protocol server that exposes Cypress as a set of AI-usable tools. Connect it to Claude, Cursor, VS Code, or any MCP client and let your AI assistant:

Run your Cypress tests and get structured pass/fail results
Read and write spec files — generate new tests from natural language
Snapshot any page via the ARIA accessibility tree — no screenshots needed
Automate a browser — navigate, click, type, evaluate JavaScript

Think of it as the Cypress equivalent of @playwright/mcp.

How it works

Your AI (Claude / Cursor / VS Code)
        │
        │  MCP protocol (stdio or HTTP/SSE)
        ▼
   cypress-mcp server
        │
        ├── Spec tools ──────────► Filesystem (list / read / write .cy.ts files)
        ├── Runner tools ─────────► Cypress CLI (run tests, open GUI, get results)
        └── Browser tools ────────► Playwright-core (navigate, snapshot, screenshot)

Browser automation uses a separate Playwright-core instance — not the Cypress browser — keeping automation and testing concerns cleanly separated.

Quick Start

1. Install browsers (one-time)

npx playwright install chromium

2. Connect to your MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

VS Code / Cursor (HTTP/SSE mode):

npx cypress-mcp --port 8932 --project /path/to/your/app

Then point your MCP client at http://localhost:8932/sse.

3. Start asking your AI

> List the spec files in my project
> Navigate to http://localhost:3000/login and take a snapshot
> Write a Cypress test for the login form based on what you see
> Run the login spec and tell me what failed

Tools

Spec file tools

Tool	Description
`cypress_list_specs`	List all spec files matching Cypress patterns
`cypress_read_spec`	Read a spec file's contents
`cypress_write_spec`	Create or overwrite a spec file
`cypress_get_config`	Read `cypress.config.ts/js`

Test runner tools

Tool	Description
`cypress_run`	Run tests — returns pass/fail counts and error details
`cypress_open`	Open Cypress GUI
`cypress_get_last_run`	Read results from the last run

Browser automation tools

Tool	Description
`cypress_navigate`	Navigate to a URL
`cypress_snapshot`	Get ARIA accessibility tree of the page
`cypress_screenshot`	Take a screenshot (full page or element)
`cypress_click`	Click an element by selector or text
`cypress_type`	Type into an input field
`cypress_evaluate`	Run JavaScript and return the result
`cypress_get_url`	Get the current URL
`cypress_wait_for`	Wait for an element or text to appear
`cypress_close_browser`	Close the automation browser

Example workflow

Here's what happens when you ask an AI to write tests for your app:

1. Snapshot the page — cypress_navigate + cypress_snapshot

Accessibility Snapshot:
- heading "My Todo List" [level=1]
- textbox "New todo"
- button "Add"
- list "Todo list"
  - listitem: No todos yet. Add one above!

2. AI writes a spec — cypress_write_spec

describe('Todo App', () => {
  it('adds a new todo', () => {
    cy.visit('http://localhost:4000');
    cy.get('[aria-label="New todo"]').type('Buy groceries');
    cy.get('button').contains('Add').click();
    cy.get('#todo-list').should('contain', 'Buy groceries');
  });
});

3. Run the tests — cypress_run

✅ Cypress Run PASSED
Tests:    10
Passed:   10
Failed:   0
Duration: 3.21s

CLI Options

cypress-mcp [options]

  --project <path>    Cypress project root (default: current directory)
  --port <number>     Start HTTP/SSE server instead of stdio
  --browser <name>    Browser for automation: chromium | firefox | webkit (default: chromium)
  --headed            Show the automation browser window
  --help              Show help
  --version           Show version

Running Locally

git clone https://github.com/yashpreetbathla/cypress-mcp.git
cd cypress-mcp
npm install
npx playwright install chromium
npm run build
npm test

Development mode

npm run dev        # TypeScript watch mode
npm test           # Run unit tests (Vitest)
npm run test:watch # Watch mode

Requirements

Requirement	Version
Node.js	>= 18
Cypress (in your project)	>= 12
Chromium (for browser tools)	via `npx playwright install chromium`

Cypress is a peer dependency — install it in your project, not globally. The MCP server picks it up automatically from node_modules/.bin/cypress.

Architecture

cypress-mcp/
├── src/
│   ├── index.ts          CLI entry point
│   ├── server.ts         MCP server (stdio + HTTP/SSE transports)
│   ├── context.ts        Playwright-core browser context singleton
│   ├── toolHandler.ts    Central tool dispatcher
│   ├── tools/
│   │   ├── specs.ts      Spec file management (filesystem)
│   │   ├── runner.ts     Cypress test execution (CLI)
│   │   └── browser.ts    Browser automation (Playwright-core)
│   ├── types.ts          TypeScript interfaces
│   └── version.ts        Version constant
└── tests/
    └── unit/
        ├── specs.test.ts      13 tests for file tools
        ├── tools.test.ts       8 tests for tool definitions
        └── toolHandler.test.ts 4 tests for dispatch logic

Why Playwright-core for browser automation?

Cypress is a testing framework — its browser isn't accessible as a real-time automation API. Rather than try to hack into the Cypress browser, cypress-mcp runs a lightweight separate Playwright-core instance for automation tasks (navigate, snapshot, screenshot). The Cypress browser is only used when running actual tests via cypress_run.

Comparison with @playwright/mcp

Feature	`cypress-mcp`	`@playwright/mcp`
Browser automation	✅ (via Playwright-core)	✅ (native)
Accessibility snapshot	✅ ARIA tree	✅ ARIA tree
Run existing tests	✅ Cypress tests	❌
Write test files	✅ `.cy.ts` / `.cy.js`	❌
Test results parsing	✅ structured JSON	❌
Vision / coordinate tools	❌ (coming)	✅
Best for	Teams using Cypress for E2E	General browser automation

Contributing

Issues and PRs welcome. Please open an issue before starting significant work.

npm test             # must pass
npm run build        # must compile cleanly

cypress-mcp

cypress-mcp

What is this?

How it works

Quick Start

1. Install browsers (one-time)

2. Connect to your MCP client

3. Start asking your AI

Tools

Spec file tools

Test runner tools

Browser automation tools

Example workflow

CLI Options

Running Locally

Development mode

Requirements

Architecture

Why Playwright-core for browser automation?

Comparison with @playwright/mcp

Contributing

License

Latest Blog Posts

MCP directory API