cypress MCP server
Commit Nov 10, 2026Enables AI agents to execute, debug, and iterate on Cypress end-to-end tests directly within their conversation.
Also known as jams4code/cypress-mcp
- Stars
- 1
- Tools
- 11
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 10, 2026
- License
- Apache-2.0
What is cypress MCP?
cypress enables AI agents to execute, debug, and iterate on Cypress end-to-end tests directly within their conversation. It exposes 11 tools, such as cypress_discover, cypress_analyze_spec, cypress_list_specs.
Summary generated from the project's README
About cypress MCP server
Automating the execution and debugging of end-to-end tests is what cypress-mcp enables for developers using AI coding agents. By integrating with clients like Claude Code, Cursor, or Windsurf, this server allows an agent to run Cypress specs, inspect failures, and iterate on code without requiring the user to manually switch to a terminal. It operates locally by spawning the Cypress runtime as a child process, ensuring that test results, screenshots, and error contexts are delivered directly into the conversation.
The server provides twelve specialized tools for a complete testing lifecycle, including discovery tools to map the test suite and debugging tools to retrieve failure context or screenshots. It supports Cypress versions 12.x through 16.x and requires Node.js 22.12 or higher. For teams using Cypress Cloud, the server can record local runs by passing a record key through environment variables, allowing agents to bridge local execution with cloud-based analytics and history.
What you can do with it
- 1Identifying flaky testsThe agent can detect unstable tests by checking if they passed after multiple attempts within a single run.
Written from the project's README. Every use case is checked against a quote from it.
How to install cypress MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall cypress MCP in Claude Code
$ claude mcp add cypress-mcp -- npx -y cypress-mcpInstall cypress MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"cypress-mcp": {
"command": "npx",
"args": [
"-y",
"cypress-mcp"
]
}
}
}Install cypress MCP in VS Code
.vscode/mcp.json
{
"servers": {
"cypress-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"cypress-mcp"
]
}
}
}Install cypress MCP in VS Code CLI
$ code --add-mcp '{"name":"cypress-mcp","type":"stdio","command":"npx","args":["-y","cypress-mcp"]}'Install cypress MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"cypress-mcp": {
"command": "npx",
"args": [
"-y",
"cypress-mcp"
]
}
}
}Install cypress MCP in Codex
$ codex mcp add cypress-mcp -- npx -y cypress-mcpInstall cypress MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.cypress-mcp] command = "npx" args = ["-y", "cypress-mcp"]
Install cypress MCP in Gemini CLI
$ gemini mcp add -s user cypress-mcp npx -- -y cypress-mcpInstall cypress MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"cypress-mcp": {
"command": "npx",
"args": [
"-y",
"cypress-mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for cypress-mcp 0.1.1 in an isolated container with no network and no keys. It answered and listed 11 tools.
cypress MCP tools 11
Read from the server with tools/listcypress_discoverDiscover 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_specDeep 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_specsList all Cypress spec files in the project. Returns file paths and test counts.
cypress_run_specRun a single Cypress spec file headless. Returns structured results with pass/fail counts, failure details, screenshot paths, and recommended next actions.
cypress_run_testRun a specific test by name within a spec file using grep. Returns structured results with recommended next actions for the agent.
cypress_rerun_lastReplay 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_runReturn the full structured results of the most recent Cypress test run including runId, args used, and all test details.
cypress_get_failure_contextGet 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_screenshotFind screenshot files from Cypress test failures. Returns absolute file paths that multimodal AI agents can read directly.
cypress_get_envReturn the contents of cypress.env.json with sensitive values masked. Safe to display.
cypress_doctorComprehensive health check of the Cypress project. Validates config file, binary, spec files, support file, and directories. Use this to diagnose setup issues.
Configuration
CYPRESS_RECORD_KEY
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablejams4code/cypress-mcp is public and reachablegithub.com/jams4code/cypress-mcp ↗Pass
- Package names this repository as its sourcecypress-mcp names jams4code/cypress-mcp as sourcenpmjs.com/package/cypress-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/jams4code/cypress-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from cypress-mcpPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model12 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubcypress-mcp
MCP server that gives AI coding agents full control over Cypress test execution.
Run, debug, and iterate on E2E tests directly from Claude Code, Cursor, Windsurf, or any MCP-compatible agent, without switching to a terminal. Works alongside Cypress Cloud MCP: record local runs to Cloud and hand the run URL straight to its tools.
Install
| Package Manager | Command |
|---|---|
| npx (no install) | npx cypress-mcp --cwd /path/to/project |
| npm | npm install -g cypress-mcp |
| pnpm | pnpm add -g cypress-mcp |
| yarn | yarn global add cypress-mcp |
| bun | bun add -g cypress-mcp |
| From GitHub | npx github:jams4code/cypress-mcp |
Quick Start
Register with your MCP client:
Claude Code:
claude mcp add cypress-mcp -- npx cypress-mcp --cwd /path/to/project
Cursor / VS Code:
{
"mcpServers": {
"cypress": {
"command": "npx",
"args": ["cypress-mcp", "--cwd", "/path/to/your/project"]
}
}
}
Windsurf:
{
"mcpServers": {
"cypress": {
"command": "npx",
"args": ["cypress-mcp", "--cwd", "/path/to/your/project"]
}
}
}
Why
AI agents can write Cypress tests but can't run them. Every change requires you to switch to terminal, run npx cypress run, wait, copy the output back. This kills iteration speed.
cypress-mcp closes the loop. The agent runs specs, reads failures, views screenshots, inspects crash context, spots flaky tests, reruns the last command, and discovers the test suite, all within the conversation.
Tools (12)
Core Loop
| Tool | What it does |
|---|---|
cypress_run_spec |
Run a spec file headless, get structured JSON results (optionally recorded to Cypress Cloud) |
cypress_run_test |
Run a single test by name (grep filter) |
cypress_rerun_last |
Replay the exact last run without rebuilding arguments |
cypress_list_specs |
List all spec files with test counts |
Debug
| Tool | What it does |
|---|---|
cypress_get_failure_context |
Compact debugging bundle: error, stack, spec excerpt, screenshots, next actions |
cypress_get_screenshot |
Find failure screenshots by spec or test name |
cypress_get_last_run |
Full results of the most recent run, including per-test attempts and flaky flags |
Discovery
| Tool | What it does |
|---|---|
cypress_discover |
Map the entire test suite: specs, test names, counts |
cypress_analyze_spec |
Deep-parse a spec: describe blocks, visits, intercepts, fixtures |
Setup
| Tool | What it does |
|---|---|
cypress_get_config |
Resolved configuration and Cypress Cloud status (projectId, record key present) |
cypress_get_env |
Show cypress.env.json (secrets masked) |
cypress_doctor |
Health check: config, binary, specs, support file, Cloud setup, directories |
How It Works
graph LR
A[AI Agent] -->|stdio JSON-RPC| B[cypress-mcp]
B -->|child_process.spawn| C[Cypress Runtime]
C -->|JSON reporter| B
B -->|structured result| A
style A fill:#1a1a2e,stroke:#e94560,color:#fff
style B fill:#16213e,stroke:#0f3460,color:#fff
style C fill:#0f3460,stroke:#533483,color:#fff
- stdio transport: the agent spawns the server as a child process
- Serial execution: one Cypress run at a time, no concurrency
- Structured output: JSON results with failure details, diffs, screenshot paths, attempts and flaky flags
- Config-aware: auto-detects
cypress.config.*, follows relative imports, respects custom paths - No shell: Cypress is started with
nodedirectly and every argument is passed verbatim, so test names and paths with spaces, quotes or&are safe on every platform - Stays in the project: spec paths outside the project root are rejected
- Cross-platform: Windows, macOS, Linux
Agent Workflow
graph TD
D[cypress_discover] -->|map test suite| E[cypress_analyze_spec]
E -->|understand spec| F[cypress_run_spec]
F -->|tests fail| G[cypress_get_failure_context]
G -->|error + excerpt + screenshots| H[Fix the code]
H -->|iterate| I[cypress_rerun_last]
I -->|still failing| G
I -->|passing| J[Done]
F -->|tests pass| J
style D fill:#1a1a2e,stroke:#e94560,color:#fff
style F fill:#16213e,stroke:#0f3460,color:#fff
style G fill:#e94560,stroke:#fff,color:#fff
style I fill:#0f3460,stroke:#533483,color:#fff
style J fill:#2d6a4f,stroke:#40916c,color:#fff
Flaky Tests
With test retries enabled, every test result carries attempts and flaky. A test is flaky when it failed and then passed within the same run, the same rule Cypress Cloud uses. Run summaries count them (All 12 tests passed in login.cy.ts (1 flaky)), so the agent sees instability on the first run instead of after it reaches CI.
Cypress Cloud
cypress-mcp runs tests on your machine. Cypress Cloud MCP reads results recorded in Cypress Cloud: run history, flaky test analytics, Test Replay, UI Coverage and Accessibility. They do different jobs and work well together. No tool names overlap, so an agent can load both.
Record a local run. Pass record: true to cypress_run_spec or cypress_run_test, with optional tags, group and ciBuildId. The result includes the Cloud run:
"cloud": {
"runUrl": "https://cloud.cypress.io/projects/abc123/runs/42",
"projectId": "abc123",
"runNumber": 42
}
When a recorded run fails, nextActions points the agent at Cloud MCP's cypress_get_failed_tests with that URL, for Test Replay links and history.
Setup. Recording needs a projectId (read from your Cypress config, CYPRESS_PROJECT_ID, or cypress-mcp.config.json) and a record key. The key goes in the server environment, never in a tool call, so it never passes through the agent:
{
"mcpServers": {
"cypress": {
"command": "npx",
"args": ["cypress-mcp", "--cwd", "/path/to/your/project"],
"env": { "CYPRESS_RECORD_KEY": "your-record-key" }
},
"cypress-cloud": {
"type": "http",
"url": "https://mcp.cypress.io/mcp"
}
}
}
cypress_doctor reports whether recording is ready. Recording is opt-in per call and counts toward your Cypress Cloud test results.
Configuration
Works out of the box for standard Cypress projects. For custom setups, create cypress-mcp.config.json:
{
"defaultBrowser": "chrome",
"defaultTimeout": 600000,
"cypressConfigFile": "config/cypress.config.ts",
"specPattern": ["e2e/**/*.cy.ts"],
"supportFile": "support/e2e.ts",
"titleFilterSupport": true,
"screenshotsDir": "cypress/screenshots",
"projectId": "abc123"
}
cypress_run_test filters by test title through @cypress/grep. It is detected automatically when the plugin is registered in your support file or config. The filter is passed with --expose on Cypress 15.10+ (where @cypress/grep 7 reads it) and with --env for older plugin versions.
Env values passed to the run tools reach your tests through cy.env() on Cypress 15.10+ and Cypress.env() on older versions. They are sent as one JSON argument, so commas, quotes and string types are preserved.
Supported Versions
- Cypress 12.x to 16.x
- Node.js 22.12+ (Node 18 and 20 are end of life)
- Windows, macOS, Linux
Registry Status
| Registry | Package | Status |
|---|---|---|
| npm | cypress-mcp |
Published |
| GitHub | jams4code/cypress-mcp |
Source |
Development
git clone https://github.com/jams4code/cypress-mcp.git
cd cypress-mcp
npm install
npm run build
npm test
License
Apache License 2.0. Free to use, modify and distribute, including commercially and in CI.
Copyright (c) 2026 JADEV GROUP SARL (BE1027.114.687), Brussels, Belgium. See NOTICE.
cypress MCP questions
How do I add cypress MCP to Claude Code?
Run claude mcp add cypress-mcp -- npx -y cypress-mcp in your terminal. Add --scope user to make it available in every project.
How do I add cypress MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does cypress MCP provide?
It exposes 11 tools, including cypress_discover, cypress_analyze_spec, cypress_list_specs, cypress_run_spec, cypress_run_test.
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.