Skip to main content
Glama
cypress-runner-mcp

cypress-runner-mcp

by guyco6742

πŸ§ͺ Cypress MCP Server

License: MIT TypeScript MCP

A Model Context Protocol (MCP) server that enables AI agents (like Claude, GPT, etc.) to interact with and control Cypress test runners. This allows AI assistants to run tests, monitor execution, retrieve results, and manage test artifacts directly.


πŸš€ Features

  • βœ… Run Cypress tests via AI commands

  • πŸ“Š Real-time test monitoring with live output

  • 🎯 Flexible test execution (single spec, filtered tests, or entire suites)

  • πŸ“Έ Screenshot and video management for test failures

  • πŸ” Test discovery - automatically list all available spec files

  • ⏹️ Process control - start, stop, and monitor test runs

  • 🌐 Multi-browser support (Chrome, Firefox, Edge, Electron)

  • πŸ”„ Background execution - tests run asynchronously

  • πŸ“ Detailed status reporting with exit codes and duration


Related MCP server: cypress-mcp

πŸ“‹ Table of Contents


πŸ“¦ Installation

Prerequisites

  • Node.js >= 18.0.0

  • npm or pnpm or yarn

  • Cypress installed in your project

  • An MCP-compatible client (e.g., Cursor IDE, Claude Desktop)

Install Dependencies

# Clone the repository
git clone https://github.com/guyco6742/cypress-runner-mcp.git
cd cypress-runner-mcp

# Install dependencies (choose one)
npm install
# or
pnpm install
# or
yarn install

Build the Project

npm run build

This compiles TypeScript to JavaScript in the dist/ folder.


βš™οΈ Configuration

For Cursor IDE

Add this configuration to your .cursor/mcp.json:

{
  "mcpServers": {
    "cypress-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/cypress-mcp-server/dist/index.js"],
      "env": {
        "CYPRESS_WORKSPACE": "/absolute/path/to/your/cypress/project"
      }
    }
  }
}

For Claude Desktop

Add this to your Claude Desktop MCP config file:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cypress-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/cypress-mcp-server/dist/index.js"],
      "env": {
        "CYPRESS_WORKSPACE": "/absolute/path/to/your/cypress/project"
      }
    }
  }
}

Environment Variables

  • CYPRESS_WORKSPACE: (Required) Absolute path to your Cypress project root directory

Restart Your Client

After configuration, restart Cursor IDE or Claude Desktop for changes to take effect.


πŸ”§ Available Tools

cypress_run_spec

Run a specific Cypress test spec file.

Parameters:

  • spec (required): Path to spec file relative to workspace (e.g., cypress/e2e/login.cy.ts)

  • browser (optional): Browser to use (chrome, firefox, electron, edge) - default: chrome

  • headed (optional): Run with visible browser window - default: true

  • grep (optional): Run only tests matching this pattern (test title filter)

Example:

Run the login test in Chrome with headed mode

cypress_run_all

Run all Cypress tests in a project.

Parameters:

  • project (required): Project name or path

  • browser (optional): Browser to use - default: chrome

Example:

Run all tests in the e2e project

cypress_stop

Stop the currently running Cypress test.

Example:

Stop the current test

cypress_status

Get current test execution status with recent output.

Parameters:

  • outputLines (optional): Number of recent output lines to include - default: 30

Example:

What's the status of the running test?

cypress_output

Get the full console output from the current or last test run.

Parameters:

  • lines (optional): Number of lines to return from the end - default: 100

  • filter (optional): Filter output to lines containing this text

Example:

Show me the test output filtered for "error"

cypress_list_specs

List all available Cypress spec files in a project.

Parameters:

  • project (required): Project name or path

  • filter (optional): Filter specs by name pattern

Example:

List all spec files in the e2e project containing "login"

cypress_screenshots

List or get screenshots from test failures.

Parameters:

  • project (optional): E2E project name

  • latest (optional): Get only the most recent screenshot

Example:

Show me the latest screenshot from test failures

cypress_clear_artifacts

Clear screenshots and videos from previous test runs.

Parameters:

  • project (required): Project name to clear artifacts from

Example:

Clear all test artifacts from the e2e project

πŸ“š Resources

The server exposes these resources that can be read by AI agents:

cypress://output/live

Real-time console output from running Cypress tests.

MIME Type: text/plain

cypress://status

Current test execution status (JSON format).

MIME Type: application/json

Response Structure:

{
  "isRunning": true,
  "currentSpec": "cypress/e2e/login.cy.ts",
  "startTime": "2024-01-25T10:30:00.000Z",
  "lastExitCode": null,
  "outputLines": 42
}

πŸ’‘ Usage Examples

Example 1: Run a Specific Test

User: "Run the login test in Chrome"

AI Agent:

  1. Calls cypress_list_specs to find available tests

  2. Calls cypress_run_spec with spec: "cypress/e2e/login.cy.ts"

  3. Reports test has started


Example 2: Monitor Test Progress

User: "Check the status of the current test"

AI Agent:

  1. Calls cypress_status

  2. Returns formatted status with recent output


Example 3: Debug Failed Test

User: "Show me why the test failed"

AI Agent:

  1. Calls cypress_output with filter: "error"

  2. Calls cypress_screenshots with latest: true

  3. Provides error output and screenshot location


Example 4: Run Tests with Filtering

User: "Run only the authentication tests in Firefox"

AI Agent:

  1. Calls cypress_run_spec with:

    • spec: "cypress/e2e/auth.cy.ts"

    • browser: "firefox"

    • grep: "authentication"


πŸ“ Project Structure

cypress-mcp-server/
β”œβ”€β”€ src/
β”‚   └── index.ts          # Main MCP server implementation
β”œβ”€β”€ dist/                 # Compiled JavaScript (generated)
β”œβ”€β”€ .gitignore            # Git ignore rules
β”œβ”€β”€ package.json          # Dependencies and scripts
β”œβ”€β”€ tsconfig.json         # TypeScript configuration
β”œβ”€β”€ README.md             # This file
β”œβ”€β”€ LICENSE               # MIT License
└── SETUP.md              # Detailed setup guide

πŸ› οΈ Development

Run in Development Mode

npm run dev

This uses ts-node to run TypeScript directly without compilation.

Build for Production

npm run build

Start Production Server

npm start

Run Tests (if you add them)

npm test

πŸ› Troubleshooting

Issue: "Cypress not found"

Solution: Ensure Cypress is installed in your workspace:

cd /path/to/your/cypress/project
npm install cypress --save-dev

Issue: "Permission denied" when running tests

Solution: On Unix systems, make sure the script is executable:

chmod +x dist/index.js

Issue: Tests not starting

Solution: Check the following:

  1. Verify CYPRESS_WORKSPACE environment variable is set correctly

  2. Ensure the workspace path exists and contains Cypress config

  3. Check that Node.js version is >= 18.0.0

  4. Review server logs in your MCP client


Issue: "Cannot find module '@modelcontextprotocol/sdk'"

Solution: Reinstall dependencies:

rm -rf node_modules package-lock.json
npm install
npm run build

🀝 Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

Code Style

  • Use TypeScript strict mode

  • Follow existing code formatting

  • Add comments for complex logic

  • Update documentation for new features


πŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.


🌟 Acknowledgments


πŸ“ž Support

If you encounter issues or have questions:

  1. Check the Troubleshooting section

  2. Search existing issues

  3. Create a new issue with details


πŸ—ΊοΈ Roadmap

  • Support for Cypress component testing

  • Integration with CI/CD pipelines

  • Test report generation

  • Custom assertion helpers

  • Multi-project support

  • Video streaming for live test viewing

  • Test code generation from natural language


Made with ❀️ for the testing community

Available Tools

8 tools
cypress_clear_artifactsA

Clear screenshots and videos from previous test runs

Inputs: project (required).

cypress_list_specsA

List all available Cypress spec files in a project

Inputs: project (required), filter.

cypress_outputA

Get the full console output from the current or last test run

Inputs: lines, filter.

cypress_run_allB

Run all Cypress tests in a project

Inputs: project (required), browser.

cypress_run_specA

Run a specific Cypress test spec file. Returns immediately and runs in background.

Inputs: spec (required), grep, headed, browser.

cypress_screenshotsB

List or get screenshots from test failures

Inputs: latest, project.

cypress_statusB

Get current test execution status, including if tests are running and recent output

Inputs: outputLines.

cypress_stopA

Stop the currently running Cypress test

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 8 tools

    Disambiguation4/5

    Each tool targets a distinct part of the Cypress workflow: running, stopping, checking status, getting output, listing specs, and managing artifacts. Status and output overlap slightly since status mentions recent output, but their intended separation is clear.

    Naming Consistency4/5

    All tools share the cypress_ prefix and mostly follow a verb_noun pattern like cypress_run_spec and cypress_list_specs. cypress_status and cypress_output are noun-oriented rather than verb-oriented, but the overall pattern remains predictable.

    Tool Count5/5

    Eight tools is well-scoped for a Cypress runner server. Each tool covers a necessary part of the execution lifecycle without redundancy or bloat.

    Completeness4/5

    The surface covers running specs, running all tests, stopping, checking status, retrieving output, listing specs, and managing failure artifacts. Minor gaps exist around detailed result reporting or video retrieval, but core workflows are fully supported.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to perform comprehensive web application testing including visual, functional, performance, accessibility, and SEO analysis using browser automation without requiring API keys.
      7
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server that gives AI coding agents full control over Cypress test execution, allowing them to run, debug, and iterate on E2E tests directly from MCP-compatible agents.
      11
      1,454 npm
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Exposes Cypress as AI-usable tools for running tests, managing spec files, taking accessibility snapshots, and automating a browser via Playwright-core.
      1,454 npm
      13
      Business Source 1.1
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI models (Claude, ChatGPT, GitHub Copilot) to run and analyze local tests, rerun failures, and orchestrate QA workflows using existing UI and API test frameworks.
      13 npm
      MIT