Cypress MCP server
A maintained MCP server that runs your Cypress E2E suite from an agent, returns structured results, and surfaces failure context.
Cypress MCP is a maintained Model Context Protocol server that turns your existing Cypress end-to-end test suite into a set of tools an AI agent can drive. Instead of you running npx cypress run and pasting the output, the agent executes specs directly, gets structured JSON results back, and can iterate: run a whole spec, run a single test by grep filter, or replay the previous run without rebuilding arguments. It is built for the debug loop rather than test generation.
Where it earns its keep is failure triage. The agent can pull a debugging bundle for a failed run with errors, stack traces, and screenshots, locate screenshots by spec or test name, and read the full results of the most recent execution. It can also map the suite (discover specs and test names), analyze a spec for its describe blocks, visits, and intercepts, inspect cypress.env.json with secrets masked, and run a health check on the Cypress config, binary, and directories. It runs locally over stdio via npx with a --cwd pointing at your project, so the agent operates on your real Cypress setup. For teams already invested in Cypress, it lets an assistant run, read, and reason about the suite without leaving the editor.
Quick install
Copy-paste configs are provided for all 8 supported clients. Pick your client below.
Available tools
| Tool | Description |
|---|---|
| cypress_run_spec | Executes a spec file headless and returns structured JSON results. |
| cypress_run_test | Executes a single test using a grep filter. |
| cypress_rerun_last | Replays the previous run without rebuilding arguments. |
| cypress_list_specs | Enumerates all spec files with their test counts. |
| cypress_get_failure_context | Retrieves a debugging bundle with errors, stack traces, and screenshots for a failed run. |
| cypress_get_screenshot | Locates failure screenshots by spec or test name. |
| cypress_get_last_run | Returns the full results from the most recent execution. |
| cypress_discover | Maps the entire test suite structure and test names. |
| cypress_analyze_spec | Parses a spec file for its describe blocks, visits, and intercepts. |
| cypress_get_env | Displays cypress.env.json with secrets masked. |
| cypress_doctor | Runs a health check on the Cypress config, binary, and directories. |
What you can do with it
Run a failing spec and triage it
The agent runs the spec, reads the structured results, then pulls the failure context bundle with stack traces and screenshots to explain exactly why a test broke and propose a fix.
Map and target the suite
Using cypress_discover and cypress_list_specs, the agent learns the structure of your tests and then runs just the single failing test by grep filter instead of the whole suite.
FAQ
- Is it free?
- Yes to use. It is published on npm as cypress-mcp under the Business Source License 1.1 (which converts to Apache 2.0 in 2029); you run it against your own Cypress project, and Cypress itself is open source.
- Does it support remote/OAuth?
- No. It runs locally over stdio via npx -y cypress-mcp, pointed at your project with the --cwd flag. There is no remote endpoint or login; it drives the Cypress binary on your machine.
- Does it generate tests or just run them?
- It focuses on running and debugging your existing suite: executing specs, returning structured results, and surfacing failure context, screenshots, and config health. It is a run-and-debug tool, not a page-object or test generator.