Open source · Outillage QA et IA
The AI agent wrote the test. Now it runs it too.
A coding agent can write a Cypress test but cannot run it. Every failure went back through a developer who pasted terminal output into the chat. cypress-mcp closes that loop: the agent runs the spec, reads a structured failure, fixes the code and reruns. We built it for our own teams, then published it as open source.
claude mcp add cypress-mcp -- npx cypress-mcp --cwd /path/to/project- License
- Apache-2.0
- Runtime
- Node.js 22.12+
- Language
- TypeScript
The problem
Claude Code, Cursor and the other coding agents write correct Cypress tests most of the time. They cannot run them. So the developer ran the command, waited, pasted the output into the conversation, and did it again after every fix.
That manual loop cost more than the test itself. And the agent worked from truncated output: no screenshot, no context around the failing line, no difference between a broken test and a flaky one.
Our teams maintain end-to-end suites on products in production. The agent had to be able to prove a feature works on its own, with the same guardrails as an engineer.
What we did
We wrote an MCP (Model Context Protocol) server in TypeScript that exposes Cypress to the agent as twelve tools: run a spec, run one test by name, replay the last run, read a failure's context, find a screenshot, map the suite and diagnose the setup.
Every response uses the same JSON envelope: a status, a one-line summary, the data and the recommended next action. The agent does not decode a terminal. It reads a structured result that includes how many attempts each test took. A test that fails and then passes on retry is marked flaky, using the same rule as Cypress Cloud.
Security is a requirement, not an option. Cypress starts without a shell, so a test name containing "&" cannot run a command on Windows. A spec path that leaves the project is rejected. The Cypress Cloud record key stays in the server's environment and never passes through the agent.
The server complements the official Cypress Cloud MCP instead of competing with it. Ours runs tests locally; Cypress's reads recorded history. A run started with recording returns the run URL, which the Cloud tools accept directly. An automated test guarantees none of our tool names collide with theirs.
Where it stands
cypress-mcp is published on npm and GitHub. It had around 450 weekly downloads on npm in mid-October 2026, with no promotion.
Since version 0.2.0, in October 2026, it is licensed under Apache 2.0, including commercial use and CI. The decision came from an engineering team that wanted to adopt it and checked the terms first. We would rather a tool be used than negotiated.
Every change goes through CI on Windows, macOS and Linux with Node 22 and 24, a CodeQL scan, and an end-to-end suite that drives a real Cypress project, version 14 and the latest, through the MCP protocol exactly as an agent would. That suite also runs weekly, so a new Cypress release that breaks something is caught by us before users hit it.
We publish no user count and no time-saved figure. npm counts downloads, not teams, and we have no controlled measure of the time saved.
- TypeScript
- Node.js 22
- Model Context Protocol
- Cypress
- Vitest
- GitHub Actions
- CodeQL
Strict TypeScript and the official MCP SDK, because the server runs on a developer's machine with whatever arguments an agent sends it. Types and tests are the first line of defense.
Frequently asked questions
- Is cypress-mcp a client project?
- No. It is a tool we built for our own teams and maintain as open source. We cite it as engineering evidence, not as a client endorsement.
- Do we need a commercial license to use it at work?
- No. Since version 0.2.0, cypress-mcp is licensed under Apache 2.0: commercial use, locally or in CI, with no fee.
- Does it replace Cypress Cloud MCP?
- No, it complements it. Cypress Cloud MCP queries runs already recorded in Cypress Cloud. cypress-mcp runs tests on the developer's machine and can record the run to Cypress Cloud so both servers work together.
- Which versions are supported?
- Cypress 12 to 16 and Node.js 22.12 or newer, on Windows, macOS and Linux. Running a single test by name relies on @cypress/grep.
- Can you set it up in our team?
- Yes. We set up Cypress or Playwright on your critical journeys, the CI and the AI tooling, or we add a QA engineer to your team from EUR 150 a day, following our public rate card.
Do your E2E tests really protect production?
Describe your application, your CI and what breaks today, without confidential code. We reply with a scope and a price.
Describe my need- Cypress MCP server: let the AI agent run your E2E testsCoding agents write Cypress tests but cannot run them. What we built to close the loop, and what production taught us along the way.
- Regression testing for critical user journeysCoverage protects nobody. Three rings of tests, a ten-minute rule, and the only metric worth putting on a wall.
- E2E testing a legacy web app: the prerequisitesJava 1.5, WebForms, PHP: an E2E test does not read your code, it looks at HTML. Here are the six prerequisites that actually matter, and the real limits.
- Cypress vs Playwright: which one for your E2E testsI have shipped both to production. The architectural difference is real, but the tool is never what decides whether an E2E suite survives.
- ParkAgenda · Operations SaaS for airport parkingMulti-channel bookings reduced to a single queue, then shuttles, staff scheduling, vehicle condition capture and on-site payment.
- AutoMotoMarket.be · Used vehicle marketplaceAutoScout and mobile.de stock ingestion, CSV and XML import, verified sellers, three languages, subscription tier for dealers.
- Pavimmo · CRM migration with zero business interruptionYears of client history cleaned, mapped and reconciled, with the source system in production from the first day to the last.