The missing link
A coding agent can now write a correct Cypress test in seconds. What it cannot do is run it.
For months, our days looked like this. The agent writes the test. I run npx cypress run, wait, and paste the terminal output into the conversation. The agent fixes something, I run it again. The developer had become the agent's clipboard.
It was not just slow. The agent worked from whatever I chose to paste: the end of a stack trace, without the screenshot, without the code around the failing line, without knowing whether the test failed once or three times.
What cypress-mcp does
The Model Context Protocol (MCP) is the standard that lets an agent such as Claude Code, Cursor or Windsurf call external tools. cypress-mcp is an MCP server that exposes Cypress as twelve tools. The ones used most fit in a single loop:
cypress_run_specruns a spec headless and returns a structured result.cypress_run_testruns one test, chosen by name.cypress_get_failure_contextgathers the error, the stack, the spec excerpt and the screenshots.cypress_rerun_lastreplays the last run exactly, after a fix.
Every response uses the same envelope. Here is, simplified, what the agent receives after a failure:
{
"ok": true,
"tool": "cypress_run_spec",
"summary": "1 failing, 3 passing in cypress/e2e/checkout.cy.ts (1 flaky)",
"data": { "stats": { "tests": 4, "passing": 3, "failing": 1, "flaky": 1 } },
"nextActions": ["cypress_get_failure_context"]
}ok is true because the tool worked, even though a test failed. nextActions tells the agent what to do next. It no longer has to guess.
Three things a terminal does not tell an agent
A flaky test is not a broken test. Cypress can retry a failing test. cypress-mcp counts the attempts for each test and marks one that fails and then passes as flaky, using the same rule as Cypress Cloud. Without that, an agent "fixes" a test that was never broken.
A failure needs its context. The error message alone is not enough. The context tool returns the failing spec line with what surrounds it, and the path of the screenshot taken at the moment of failure.
The loop has to be short. Replaying the last run without rebuilding the arguments, running one test instead of the whole spec: that is what makes iteration bearable, for an agent and for a human.
What production taught us
A tool that runs commands on a developer's machine, with arguments sent by a model, has to be written like code exposed to the internet. Three lessons, all from real cases.
On Windows, the first version started Cypress through a shell. A test name containing & could therefore run a command. Cypress is now started directly by Node, with no shell, and a test deliberately uses a spec whose name contains & and a space.
Cypress 16 removed Cypress.env(), and @cypress/grep 7 now reads its filter from somewhere else. Without a fix, asking to run only one test would have run the whole spec, with no error at all. A silent regression is the worst case for an agent: it believes it verified something it did not. Since then, an end-to-end suite drives a real Cypress project, version 14 and the latest, on Linux and Windows, on every change and every week.
Finally, a spec path that leaves the project is rejected, and the Cypress Cloud record key never passes through the agent. It stays in the server's environment.
What about Cypress Cloud MCP?
Cypress launched its own MCP server, free on every Cypress Cloud plan. It does something different. It queries the history of runs already recorded: failed tests, flaky tests, accessibility reports, UI coverage.
cypress-mcp runs the tests on the developer's machine, before anything is recorded. The two complement each other. Start a run with recording enabled: cypress-mcp returns the run URL, and the Cypress Cloud tools accept it directly to pull up Test Replay. Our tool names never overlap with theirs, and a test checks it.
Why Apache 2.0
cypress-mcp started as an internal tool for our teams, then was published under a license that reserved commercial use. In October 2026, an engineering team that wanted to adopt it asked whether they needed a commercial license for purely local use.
The right answer was to remove the question. Since version 0.2.0, cypress-mcp is licensed under Apache 2.0, including commercial use and CI. Our business is designing software and test suites for clients, not selling tooling licenses. A tool other teams adopt teaches us more than a fee would.
Install it
With Claude Code, one line is enough:
claude mcp add cypress-mcp -- npx cypress-mcp --cwd /path/to/your/projectFor Cursor, VS Code or Windsurf, declare the same command in the client's MCP configuration. You need Node.js 22.12 or newer, and Cypress 12 to 16 installed in the project. To run a single test by name, add @cypress/grep. The source code and documentation are on GitHub.
What remains an engineer's job
An agent that runs its own tests is not a QA engineer. It does not know which journeys deserve protection. It does not know that an assertion on a label will break with the next translation. And a green test does not tell it whether it checked the right thing.
The gain is elsewhere: the engineer stops being a clipboard. They review tests that already pass and spend their time on what takes judgment. The four rules that decide whether a suite survives, stable selectors, independent tests, controlled data and a fast run, are covered in our Cypress or Playwright comparison.
To set this up in your team, or for a QA engineer to own it, here is what we offer. The project itself is described on its reference page.