Cypress MCP

What cypress-mcp MCP server does

The cypress-mcp MCP server connects an MCP client to a Cypress project and its most recent test-run artifacts. It is intended for headless cypress run workflows, including runs on a developer machine and in CI. The server can expose which tests passed or failed, the Cypress commands executed by each test, failure messages, DOM snapshots, screenshots, console errors, and network errors.

It also gives an assistant access to the project’s spec files and Cypress configuration. Configuration values that appear to contain secrets are redacted before being returned. Failed tests can include an HTML snapshot of document.body from the failure point, allowing an assistant to inspect the rendered page rather than relying only on a pasted error.

How it works

Install the package in the Cypress project, register its plugin through setupNodeEvents, and import its support module from cypress/support/e2e.ts. During a Cypress run, the support code records command activity for each test. The plugin receives that information and combines it with test results after each spec completes.

Run data is written beneath .cypress-mcp/, including last-run.json and HTML snapshots for failed tests. The MCP process reads those files when tools are called. In run mode, the captured accumulator is reset before a new run. In interactive mode, results remain accumulated for the lifetime of the Cypress process; the documented run-event behavior also requires Cypress’s experimentalInteractiveRunEvents setting for that mode.

The server supports stdio transport and Streamable HTTP. HTTP mode listens at /mcp and can use a bearer token supplied through MCP_HTTP_TOKEN; otherwise, it generates a token when starting.

Setup and configuration

Install the scoped npm package as a development dependency:

npm install -D @miroslavmyrha/cypress-mcp

Use Node.js 18 or newer and Cypress 12 or newer. Set the Cypress project root with --project; it defaults to the current directory. The default transport is stdio. HTTP mode accepts --port, whose default is 3333.

For local MCP clients, configure the server to run with npx -y @miroslavmyrha/cypress-mcp --project /absolute/path/to/your/project. Claude Desktop and Claude Code are shown as stdio clients in the project documentation. HTTP mode is documented for Ollama and custom bridges, but those names do not correspond to compatible-client slugs in this directory.

Add .cypress-mcp/ to .gitignore so generated results and snapshots are not committed.

Tools and capabilities

The cypress-mcp MCP server exposes these tools:

• list_specs finds Cypress specs, with an optional glob pattern.
• read_spec returns a spec file by relative path.
• get_config reads supported Cypress config files with secret-like values removed.
• get_last_run returns test states, errors, commands, DOM snapshot paths, and related run data.
• get_screenshot returns a last-run screenshot with path and size metadata; the image is limited to 2 MB.
• query_dom searches a failed test’s DOM snapshot with a CSS selector.
• run_spec runs one spec and waits for its exit code and summary.

Limitations and notes

The server reports the latest captured run rather than querying Cypress Cloud. It requires the plugin and support import to collect command logs and results. Screenshots and snapshots must exist in the captured run, and DOM snapshots are available for failed tests. The project uses the scoped package name @miroslavmyrha/cypress-mcp; the unscoped npm name refers to an unrelated project. The package is released under the MIT license.