Cypress MCP
MCP server: Cypress MCP
Installation
npx cypress-mcpAsk AI about Cypress MCP
Powered by Claude Β· Grounded in docs
I know everything about Cypress MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Cypress MCP Server
A Model Context Protocol (MCP) server for Cypress that enables AI systems to create, execute, and analyze automated tests for web applications through the Model Context Protocol (MCP).
π Enhanced Implementation
This project implements a robust HTTP transport with Server-Sent Events (SSE) support, following the same architecture as the Playwright MCP server. Our implementation leverages the official @modelcontextprotocol/sdk package to ensure full compliance with the MCP specification.
Features
- Standards-Compliant MCP Implementation: Implements the Model Context Protocol using the official SDK
- HTTP Transport with SSE Support: Reliable server-client communication using Server-Sent Events
- Streamable HTTP Support: Alternative transport method for compatible clients
- Natural Language Test Parsing: Convert plain English test scenarios into structured test plans
- Cypress Test Generation: Generate executable Cypress tests from structured test plans
- Test Execution: Run tests against real websites
- Test Reporting: Generate detailed reports of test execution results
- Containerized Deployment: Easy deployment using Docker
Available Tools
The Cypress MCP server provides the following categories of tools that AI systems can use to interact with web applications:
Core Testing Tools
- Test Generation: Convert natural language descriptions into executable Cypress tests
- Test Execution: Run tests against real websites and gather results
- Test Reporting: Generate detailed reports of test execution
Browser Automation Tools
Navigation Tools
cypress_navigate- Navigate to a URLcypress_go_back- Go back in browser historycypress_go_forward- Go forward in browser historycypress_reload- Reload the current page
Element Interaction Tools
cypress_click- Click on an elementcypress_double_click- Double-click on an elementcypress_type- Type text into an input elementcypress_get_text- Get the text content of an elementcypress_element_exists- Check if an element exists
Assertion Tools
cypress_assert_text- Assert element contains specific textcypress_assert_visible- Assert element visibilitycypress_assert_attribute- Assert element has attribute with valuecypress_assert_url- Assert URL matches patterncypress_assert_count- Assert number of elements matching selector
Screenshot Tools
cypress_screenshot- Take a screenshot of the pagecypress_element_screenshot- Screenshot a specific element
Wait Tools
cypress_wait_for_element- Wait for element to meet conditioncypress_wait_for_page_load- Wait for page to finish loadingcypress_wait- Wait for fixed timecypress_wait_for_request- Wait for network request
Network Tools
cypress_intercept_request- Intercept network requestscypress_mock_response- Mock network responsescypress_block_requests- Block network requests
Requirements
- Node.js 18 or newer
- Cypress 13.x or newer
- An MCP client (VS Code, Claude for VSCode, Anthropic Claude, GitHub Copilot, etc.)
Installation
Local Installation
- Clone this repository
- Install dependencies:
npm install
- Build the project:
npm run build
- Start the server:
node lib/cli-server.js http
To run in headless mode (recommended for production):
node lib/cli-server.js http --headless
Docker Installation
For easier deployment and isolation, you can use Docker:
- Build the Docker image:
docker build -t cypress-mcp .
- Run the container:
docker run -d --name cypress-mcp -p 3000:3000 -e NODE_ENV=production -e OPENAI_API_KEY=your-api-key-here -e HEADLESS=true cypress-mcp
Docker Compose Installation
Alternatively, you can use Docker Compose for easier management:
- Create a
.envfile with your environment variables:
OPENAI_API_KEY=your-api-key-here
HEADLESS=true
- Run with Docker Compose:
docker-compose up -d
VSCode Configuration
To use the Cypress MCP Server with VSCode or other AI assistants, add the following to your mcp_config.json file:
{
"mcpServers": {
"cypress": {
"serverUrl": "http://localhost:3000/sse"
}
}
}
If your client supports streamable HTTP (check your client's documentation), you can also use:
{
"mcpServers": {
"cypress": {
"serverUrl": "http://localhost:3000/mcp"
}
}
}
API Endpoints
The Cypress MCP server exposes the following endpoints:
/health- Health check endpoint (responds with 200 OK if server is running)/sse- Server-Sent Events endpoint for MCP communication/mcp- Streamable HTTP endpoint for MCP communication (alternative transport)
Environment Variables
OPENAI_API_KEY- API key for OpenAI services (used for enhanced test generation)HEADLESS- Run Cypress in headless mode (default: false)NODE_ENV- Node environment (development, production, etc.)PORT- Port to run the server on (default: 3000)
Development
Project Structure
βββ src/
β βββ cli.js # CLI entrypoint for stdin/stdout transport
β βββ cli-server.js # CLI entrypoint for HTTP transport
β βββ server.ts # HTTP server implementation
β βββ connection.ts # MCP connection management
β βββ context.ts # Test context management
β βββ tools/
β β βββ tool.ts # Base tool definitions
β β βββ navigate.ts # Navigation tools
β β βββ element.ts # Element interaction tools
β β βββ assertions.ts # Assertion tools
β β βββ screenshot.ts # Screenshot tools
β β βββ wait.ts # Wait tools
β β βββ network.ts # Network tools
β β βββ ...
βββ ...
Extending the Server
To add new tools or functionality:
- Create a new tool implementation in
src/tools/ - Register your tool in
src/tools.ts - Build the project:
npm run build - Test your changes
Testing
Run the tests with:
npm test
Troubleshooting
Common Issues
Connection Issues
If your MCP client cannot connect to the server:
- Ensure the server is running (
docker psor check your terminal) - Verify the correct port is exposed and not blocked by a firewall
- Check your
mcp_config.jsonis correctly configured - Make sure you're using the correct endpoint (/sse or /mcp)
Browser Crashes
If Cypress browser crashes:
- Increase the Docker container's memory limits
- Check for browser compatibility issues
- Make sure HEADLESS is set to true in production environments
License
MIT
Additional Resources
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Β© 2025 Cypress MCP Server Contributors
