# cypress MCP server

> Enables AI agents to execute, debug, and iterate on Cypress end-to-end tests directly within their conversation.

- Repository: https://github.com/jams4code/cypress-mcp
- Page: https://hostedmcp.org/servers/jams4code/cypress-mcp
- Transport: stdio
- Stars: 1
- License: Apache-2.0

## Install

### Claude Code

```sh
claude mcp add cypress-mcp -- npx -y cypress-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "cypress-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "cypress-mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "cypress-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "cypress-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"cypress-mcp","type":"stdio","command":"npx","args":["-y","cypress-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "cypress-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "cypress-mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add cypress-mcp -- npx -y cypress-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.cypress-mcp]
command = "npx"
args = ["-y", "cypress-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user cypress-mcp npx -- -y cypress-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "cypress-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "cypress-mcp"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `CYPRESS_RECORD_KEY` | no | no |  |

## Tools (11)

- `cypress_discover`: Discover and map the entire Cypress test suite. Returns all specs with test counts, describe blocks, and test names. Use this first to understand what tests exist before writing or running anything.
- `cypress_analyze_spec`: Deep analysis of a single spec file. Extracts describe/it blocks with line numbers, cy.visit URLs, cy.intercept routes, fixtures used, and custom commands called.
- `cypress_list_specs`: List all Cypress spec files in the project. Returns file paths and test counts.
- `cypress_run_spec`: Run a single Cypress spec file headless. Returns structured results with pass/fail counts, failure details, screenshot paths, and recommended next actions.
- `cypress_run_test`: Run a specific test by name within a spec file using grep. Returns structured results with recommended next actions for the agent.
- `cypress_rerun_last`: Replay the exact last run_spec or run_test invocation. Removes friction when iterating on the same failure — no need to reconstruct arguments.
- `cypress_get_last_run`: Return the full structured results of the most recent Cypress test run including runId, args used, and all test details.
- `cypress_get_failure_context`: Get a compact debugging bundle for the most recent failure. Returns the failing test, error, stack hint, screenshot paths, relevant spec excerpt, and recommended next actions. This is the key tool for the fix-and-rerun loop.
- `cypress_get_screenshot`: Find screenshot files from Cypress test failures. Returns absolute file paths that multimodal AI agents can read directly.
- `cypress_get_env`: Return the contents of cypress.env.json with sensitive values masked. Safe to display.
- `cypress_doctor`: Comprehensive health check of the Cypress project. Validates config file, binary, spec files, support file, and directories. Use this to diagnose setup issues.

## FAQ

### Can AI agents run Cypress tests with this server?

Yes, the server provides tools for AI agents to run spec files, individual tests, and replay the last run.

### How does the server handle test failures?

It provides a debugging bundle including errors, stack traces, spec excerpts, and screenshots to help the agent fix code.

### Does it support Cypress Cloud recording?

Yes, you can optionally record local runs to Cypress Cloud by passing the record flag and providing a record key in the environment.
