cypress-runner-mcp
This MCP server enables AI agents to run and manage Cypress tests.
Run a specific Cypress spec with optional browser, headed mode, and grep filtering.
Run all tests in a project.
Stop the currently running test.
Get current test execution status and recent output.
Retrieve full console output with optional line limit and text filter.
List available spec files with optional name filter.
List or get the latest screenshots from test failures.
Clear screenshots and videos from a project.
Read live console output (
cypress://output/live) and status (cypress://status) resources.
Provides tools to run Cypress tests, monitor execution, retrieve results, manage screenshots and videos, and list spec files, enabling AI agents to control Cypress test runners.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cypress-runner-mcp Run login tests in Chrome browser"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π§ͺ Cypress MCP Server
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 installBuild the Project
npm run buildThis 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:chromeheaded(optional): Run with visible browser window - default:truegrep(optional): Run only tests matching this pattern (test title filter)
Example:
Run the login test in Chrome with headed modecypress_run_all
Run all Cypress tests in a project.
Parameters:
project(required): Project name or pathbrowser(optional): Browser to use - default:chrome
Example:
Run all tests in the e2e projectcypress_stop
Stop the currently running Cypress test.
Example:
Stop the current testcypress_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:100filter(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 pathfilter(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 namelatest(optional): Get only the most recent screenshot
Example:
Show me the latest screenshot from test failurescypress_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:
Calls
cypress_list_specsto find available testsCalls
cypress_run_specwithspec: "cypress/e2e/login.cy.ts"Reports test has started
Example 2: Monitor Test Progress
User: "Check the status of the current test"
AI Agent:
Calls
cypress_statusReturns formatted status with recent output
Example 3: Debug Failed Test
User: "Show me why the test failed"
AI Agent:
Calls
cypress_outputwithfilter: "error"Calls
cypress_screenshotswithlatest: trueProvides error output and screenshot location
Example 4: Run Tests with Filtering
User: "Run only the authentication tests in Firefox"
AI Agent:
Calls
cypress_run_specwith: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 devThis uses ts-node to run TypeScript directly without compilation.
Build for Production
npm run buildStart Production Server
npm startRun 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-devIssue: "Permission denied" when running tests
Solution: On Unix systems, make sure the script is executable:
chmod +x dist/index.jsIssue: Tests not starting
Solution: Check the following:
Verify
CYPRESS_WORKSPACEenvironment variable is set correctlyEnsure the workspace path exists and contains Cypress config
Check that Node.js version is >= 18.0.0
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:
Fork the repository
Create a feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'Add amazing feature')Push to the branch (
git push origin feature/amazing-feature)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
Built with Model Context Protocol SDK
Designed for Cypress test automation
Inspired by the need for AI-assisted testing workflows
π Support
If you encounter issues or have questions:
Check the Troubleshooting section
Search existing issues
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 toolscypress_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
Scored across 8 tools
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.
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.
Eight tools is well-scoped for a Cypress runner server. Each tool covers a necessary part of the execution lifecycle without redundancy or bloat.
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
Related MCP Connectors
Direct access to Cypress tests results and accessibility reports in your AI workflow.
Write, run and check natural-language browser tests of your web app from your AI assistant.
Test management for AI agents: cases, runs, results, cycles and traceability.
Test analytics for AI agents: test history, flaky tests, failure clusters, coverage.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to perform comprehensive web application testing including visual, functional, performance, accessibility, and SEO analysis using browser automation without requiring API keys.7MIT
- AlicenseAqualityCmaintenanceMCP 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.111,454 npm1Apache 2.0
- AlicenseNot gradedqualityDmaintenanceExposes Cypress as AI-usable tools for running tests, managing spec files, taking accessibility snapshots, and automating a browser via Playwright-core.1,454 npm13Business Source 1.1
- AlicenseNot gradedqualityDmaintenanceEnables 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 npmMIT