Cucumber Studio

A Model Context Protocol (MCP) server that provides LLM access to Cucumber Studio's testing platform. This server enables AI assistants to retrieve test scenarios, action words, test runs, and project information from Cucumber Studio.

- Dual Transport Support- STDIO and Streamable HTTP transports with session management
- Project Management- List and retrieve project details
- Scenario Access- Browse test scenarios and search by tags
- Action Words- Access reusable test steps and definitions
- Test Execution- View test runs, executions, and build information
- Hot Reload Development- Instant server restart on file changes with tsx --watch
- Configurable Logging- Structured logging with multiple output destinations
- Comprehensive Error Handling- Robust error handling with detailed feedback
- Type Safety- Full TypeScript implementation with Zod validation
- Comprehensive Testing- 82%+ test coverage with Vitest and MSW

The easiest way to use this MCP server is as a Desktop Extension:
- Download Extension: Get the latest.mcpbfile from thereleases page(automatically built from each release)
- Install Extension: Import the extension in your compatible AI desktop application
- Configure Credentials: Set up your Cucumber Studio API credentials through the extension settings:

export CUCUMBERSTUDIO_ACCESS_TOKEN="your_token" export CUCUMBERSTUDIO_CLIENT_ID="your_client_id" export CUCUMBERSTUDIO_UID="your_uid"

git clone https://github.com/HeroSizy/cucumberstudio-mcp.git cd cucumberstudio-mcp

cp .env.example .env # Edit .env with your Cucumber Studio API credentials

# With environment file docker run --env-file .env herosizy/cucumberstudio-mcp # With environment variables docker run -e CUCUMBERSTUDIO_ACCESS_TOKEN=your_token \ -e CUCUMBERSTUDIO_CLIENT_ID=your_client_id \ -e CUCUMBERSTUDIO_UID=your_uid \ herosizy/cucumberstudio-mcp

cp .env.example .env # Edit .env with your Cucumber Studio API credentials

version: '3.8' services: cucumberstudio-mcp: image: herosizy/cucumberstudio-mcp env_file: - .env restart: unless-stopped ports: - "${MCP_PORT:-3000}:3000"

- CUCUMBERSTUDIO_BASE_URL- API base URL (default:https://studio.cucumberstudio.com/api)
- MCP_TRANSPORT- Transport type:stdio(default),http, orstreamable-http
- MCP_PORT- HTTP transport port (default: 3000)
- MCP_HOST- HTTP transport host (default: 0.0.0.0)
- MCP_CORS_ORIGIN- CORS origin setting (default: true)

# Development npm run dev # Production npm start

# Development npm run dev:http # Production npm run start:http

{ "mcpServers": { "cucumberstudio": { "command": "npx", "args": ["cucumberstudio-mcp"], "env": { "CUCUMBERSTUDIO_ACCESS_TOKEN": "your_token", "CUCUMBERSTUDIO_CLIENT_ID": "your_client_id", "CUCUMBERSTUDIO_UID": "your_uid" } } } }

{ "mcpServers": { "cucumberstudio": { "command": "node", "args": ["/path/to/cucumberstudio-mcp/build/index.js"], "env": { "CUCUMBERSTUDIO_ACCESS_TOKEN": "your_token", "CUCUMBERSTUDIO_CLIENT_ID": "your_client_id", "CUCUMBERSTUDIO_UID": "your_uid" } } } }

{ "mcpServers": { "cucumberstudio": { "command": "docker", "args": ["run", "--rm", "-i", "--env-file", "/path/to/.env", "herosizy/cucumberstudio-mcp"] } } }

{ "mcpServers": { "cucumberstudio": { "command": "docker", "args": ["run", "--rm", "-i", "--env-file", "/path/to/.env", "cucumberstudio-mcp"] } } }

- cucumberstudio_list_projects- List all accessible projects
- cucumberstudio_get_project- Get detailed project information

- cucumberstudio_list_scenarios- List scenarios in a project
- cucumberstudio_get_scenario- Get detailed scenario information
- cucumberstudio_find_scenarios_by_tags- Find scenarios by tags

- cucumberstudio_list_action_words- List reusable action words
- cucumberstudio_get_action_word- Get detailed action word information
- cucumberstudio_find_action_words_by_tags- Find action words by tags

- cucumberstudio_list_test_runs- List test runs
- cucumberstudio_get_test_run- Get detailed test run information
- cucumberstudio_get_test_executions- Get individual test results
- cucumberstudio_list_builds- List builds
- cucumberstudio_get_build- Get build details
- cucumberstudio_list_execution_environments- List execution environments

The server supports hot reload for rapid development:

# STDIO transport with hot reload npm run dev # HTTP transport with hot reload npm run dev:http

Files are automatically recompiled and the server restarts when changes are detected.

# Install dependencies npm install # Run type checking npm run typecheck # Run linting npm run lint # Build for production npm run build # Run tests npm test # Run tests in watch mode npm run test:watch # Run tests with coverage (82%+ coverage) npm run test:coverage # Run tests with UI npm run test:ui

# Production build (default) - optimized for size, no .d.ts/.js.map files npm run build # Development build - includes source maps and type declarations for debugging npm run build:dev

# Validate manifest.json npm run mcpb:validate # Build complete MCPB extension for local testing (optimized production build) npm run mcpb:build # Check info about built extension npm run mcpb:info # Clean up build artifacts npm run mcpb:clean

The server is built with a modular, production-ready architecture:

- TypeScript- Full type safety with strict configuration
- Dual Transports- STDIO for local use, Streamable HTTP for remote access
- Zod- Runtime validation for API inputs and configuration
- Axios- HTTP client with comprehensive error handling and logging
- MCP SDK- Official Model Context Protocol implementation
- Express- HTTP server with CORS, security middleware, and session management
- Vitest- Modern testing framework with 82%+ code coverage
- MSW- Mock Service Worker for realistic API testing

- Session Management- HTTP transport with session tracking and cleanup
- Comprehensive Logging- Structured logging with configurable outputs and levels
- Error Handling- Robust error handling with detailed feedback and recovery
- Security- Origin validation, CORS protection, and input sanitization
- Health Monitoring- Health check endpoints and request/response tracking
- Development Workflow- Hot reload, comprehensive testing, and Docker support

The project includes comprehensive test coverage:

# Run all tests npm test # Run tests with coverage report npm run test:coverage # Run tests in watch mode (for development) npm run test:watch

- Unit tests for all modules
- Integration tests for the MCP server
- Transport layer testing
- API client mocking and testing
- Configuration validation
- Error handling scenarios

This project uses automated releases via GitHub Actions. When a version tag is pushed, it automatically:
- Runs full test suite- Ensures code quality and coverage
- Publishes to NPM- Makes the package available vianpx cucumberstudio-mcp
- Builds and publishes Docker image- Pushes multi-platform images to Docker Hub
- Creates GitHub release- Generates release notes and links
- The GitHub Action will automatically:

- Publish to NPM:https://www.npmjs.com/package/cucumberstudio-mcp
- Push to Docker Hub:https://hub.docker.com/r/herosizy/cucumberstudio-mcp
- Create a GitHub release with changelog

- Cucumber Studio API Documentation
- Cucumber Studio API Reference
- Model Context Protocol
- MCP TypeScript SDK

Anchor Browser (https://anchorbrowser.io) is secure infrastructure for computer-use agents — stealth cloud browsers, authentication, captcha bypass, and a hosted MCP server for Cursor, Claude, and Windsurf.