cypress-mcp

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

---

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

---

License

MIT © Yashpreet Bathla