# cypress-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/miroslavmyrha/cypress-mcp  
**GitHub Stars:** 1  
**npm Downloads (last month):** 4690  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/cypress-mcp

## Description
Shows an AI assistant the last cypress run: command log, errors, screenshots, DOM of failed tests.

## Tools
Capabilities this server exposes over MCP:

- **list_specs** — List all Cypress spec files. Optional `pattern` glob (default: `**/*.cy.{ts,js,tsx,jsx}`)
- **read_spec** — Read a spec file's content by relative path
- **get_config** — Read the Cypress config file (`cypress.config.ts/js/mjs/cjs`), secret-looking values redacted
- **get_last_run** — Get results of the last test run: states, errors, command log, DOM snapshots
- **get_screenshot** — Get a screenshot from the last run. Returns the image itself (up to 2 MB) plus path and size metadata
- **query_dom** — Query the DOM snapshot of a failed test using a CSS selector
- **run_spec** — Run a single Cypress spec file and wait for completion. Returns exit code and summary

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "cypress-mcp": {
    "command": "npx",
    "args": ["-y","@miroslavmyrha/cypress-mcp"],
    "env": {
      "MCP_HTTP_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `MCP_HTTP_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/cypress-mcp/readme_