Provides tools for managing Cypress test spec files, running tests, and browser automation via Playwright-core for snapshotting, navigation, and interaction.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cypress-mcp run the login spec and report failures"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for Cypress — let AI agents run tests, manage specs, snapshot pages, and automate browsers.
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.
Related MCP server: mcp-browser
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.
npx playwright install chromiumClaude 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/appThen point your MCP client at http://localhost:8932/sse.
> 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 failedTool | Description |
| List all spec files matching Cypress patterns |
| Read a spec file's contents |
| Create or overwrite a spec file |
| Read |
Tool | Description |
| Run tests — returns pass/fail counts and error details |
| Open Cypress GUI |
| Read results from the last run |
Tool | Description |
| Navigate to a URL |
| Get ARIA accessibility tree of the page |
| Take a screenshot (full page or element) |
| Click an element by selector or text |
| Type into an input field |
| Run JavaScript and return the result |
| Get the current URL |
| Wait for an element or text to appear |
| Close the automation browser |
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.21scypress-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 versiongit clone https://github.com/yashpreetbathla/cypress-mcp.git
cd cypress-mcp
npm install
npx playwright install chromium
npm run build
npm testnpm run dev # TypeScript watch mode
npm test # Run unit tests (Vitest)
npm run test:watch # Watch modeRequirement | Version |
Node.js | >= 18 |
Cypress (in your project) | >= 12 |
Chromium (for browser tools) | via |
Cypress is a peer dependency — install it in your project, not globally. The MCP server picks it up automatically from node_modules/.bin/cypress.
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 logicCypress 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.
Feature |
|
|
Browser automation | ✅ (via Playwright-core) | ✅ (native) |
Accessibility snapshot | ✅ ARIA tree | ✅ ARIA tree |
Run existing tests | ✅ Cypress tests | ❌ |
Write test files | ✅ | ❌ |
Test results parsing | ✅ structured JSON | ❌ |
Vision / coordinate tools | ❌ (coming) | ✅ |
Best for | Teams using Cypress for E2E | General browser automation |
Issues and PRs welcome. Please open an issue before starting significant work.
npm test # must pass
npm run build # must compile cleanlyMIT © Yashpreet Bathla
This server cannot be deployed
Direct access to Cypress tests results and accessibility reports in your AI workflow.
AI-callable tools for API mocking, testing, monitoring, security, and automation.
Use your own Mac from ChatGPT, Claude or Codex: files, commands, documents, and a browser.
Provides cloud browser automation capabilities using Stagehand and Browserbase, enabling LLMs to i…
