Your AI (Claude / Cursor / VS Code)
        │
        │  MCP protocol (stdio or HTTP/SSE)
        ▼
   cypress-mcp server
        │
        ├── Spec tools ──────────► Filesystem (list / read / write .cy.ts files)
        ├── Runner tools ─────────► Cypress CLI (run tests, open GUI, get results)
        └── Browser tools ────────► Playwright-core (navigate, snapshot, screenshot)

npx playwright install chromium

{
  "mcpServers": {
    "cypress": {
      "command": "npx",
      "args": ["cypress-mcp", "--project", "/path/to/your/app"]
    }
  }
}

npx cypress-mcp --port 8932 --project /path/to/your/app

> List the spec files in my project
> Navigate to http://localhost:3000/login and take a snapshot
> Write a Cypress test for the login form based on what you see
> Run the login spec and tell me what failed

Accessibility Snapshot:
- heading "My Todo List" [level=1]
- textbox "New todo"
- button "Add"
- list "Todo list"
  - listitem: No todos yet. Add one above!

describe('Todo App', () => {
  it('adds a new todo', () => {
    cy.visit('http://localhost:4000');
    cy.get('[aria-label="New todo"]').type('Buy groceries');
    cy.get('button').contains('Add').click();
    cy.get('#todo-list').should('contain', 'Buy groceries');
  });
});

✅ Cypress Run PASSED
Tests:    10
Passed:   10
Failed:   0
Duration: 3.21s

cypress-mcp [options]

  --project <path>    Cypress project root (default: current directory)
  --port <number>     Start HTTP/SSE server instead of stdio
  --browser <name>    Browser for automation: chromium | firefox | webkit (default: chromium)
  --headed            Show the automation browser window
  --help              Show help
  --version           Show version

git clone https://github.com/yashpreetbathla/cypress-mcp.git
cd cypress-mcp
npm install
npx playwright install chromium
npm run build
npm test

npm run dev        # TypeScript watch mode
npm test           # Run unit tests (Vitest)
npm run test:watch # Watch mode

cypress-mcp/
├── src/
│   ├── index.ts          CLI entry point
│   ├── server.ts         MCP server (stdio + HTTP/SSE transports)
│   ├── context.ts        Playwright-core browser context singleton
│   ├── toolHandler.ts    Central tool dispatcher
│   ├── tools/
│   │   ├── specs.ts      Spec file management (filesystem)
│   │   ├── runner.ts     Cypress test execution (CLI)
│   │   └── browser.ts    Browser automation (Playwright-core)
│   ├── types.ts          TypeScript interfaces
│   └── version.ts        Version constant
└── tests/
    └── unit/
        ├── specs.test.ts      13 tests for file tools
        ├── tools.test.ts       8 tests for tool definitions
        └── toolHandler.test.ts 4 tests for dispatch logic

npm test             # must pass
npm run build        # must compile cleanly