Greenrun
greenrun-cli
Browser test management for Claude Code. Write tests in plain English, and Claude generates and runs Playwright scripts automatically.
Greenrun is an MCP server that connects Claude Code to the Greenrun API. You describe what to test, Greenrun handles the rest — script generation, parallel execution, result tracking, and re-running only what's needed.
Quick Start
npx greenrun-cli init
The setup wizard will:
- Validate your Greenrun API token
- Configure the Greenrun and Playwright MCP servers for Claude Code
- Install
/greenrunand/greenrun-sweepslash commands - Add project instructions to your
CLAUDE.md - Set up tool permissions so tests run without prompts
Get an API token at app.greenrun.dev/tokens.
Prerequisites
- Node.js 18+
- Claude Code — install guide
- Playwright MCP — configured automatically by
init
How It Works
- Define tests in the dashboard or via Claude Code using MCP tools
- Run
/greenrun— Claude fetches tests, generates Playwright scripts on first run, then executes them natively - Scripts are cached — subsequent runs skip generation and execute instantly via
npx playwright test - Results are tracked — pass/fail status, duration, and summaries stored per run
Script Generation
On first run, Claude walks through each test's instructions in the browser (scouting pass), observes UI states, and generates a .spec.ts script using real selectors. Scripts are saved to the API and reused on future runs.
If a cached script fails, an AI agent re-executes the test manually to determine whether the script is stale or there's a real bug. Stale scripts are automatically cleared for regeneration.
Authentication
Projects support named credential sets (name, email, password). Each test can reference a credential by name via credential_name. During execution, the matching credentials are used to authenticate before running the test.
Impact Analysis
After code changes, run /greenrun-sweep to find which tests are affected by the pages you changed. Only the relevant tests are re-run.
Slash Commands
/greenrun [filter]
Run tests for the current project. Supports filters:
/greenrun— run all active tests/greenrun tag:smoke— run tests tagged "smoke"/greenrun /checkout— run tests linked to pages matching "/checkout"/greenrun login— run tests with "login" in the name
/greenrun-sweep
Detect which tests are impacted by recent git changes and offer to run them.
MCP Tools
| Tool | Description |
|---|---|
list_projects | List all projects |
create_project | Create a project (with credentials, auth config) |
get_project | Get project details |
update_project | Update project settings |
list_pages | List pages in a project |
create_page | Register a page URL |
list_tests | List tests with latest run status |
get_test | Get full test details and instructions |
create_test | Create a test (with credential_name, tags, pages) |
update_test | Update test (auto-invalidates script on content change) |
prepare_test_batch | Fetch, filter, and start runs for a batch of tests |
export_test_script | Write a test's cached Playwright script to a local file (keeps scripts out of context) |
export_test_instructions | Write a test's instructions to a local file (keeps instructions out of context) |
sweep | Find tests affected by specific pages |
start_run | Start a test run |
complete_run | Record a single test result |
batch_complete_runs | Record results for multiple test runs in one call |
get_run | Get run details |
list_runs | List run history |
Manual Setup
If you prefer to configure manually instead of using init:
claude mcp add greenrun --transport stdio -e GREENRUN_API_TOKEN=your_token -- npx -y greenrun-cli@latest
claude mcp add playwright -- npx @playwright/mcp@latest --browser chrome --user-data-dir ~/.greenrun/browser-profile
Or add to your project's .mcp.json:
{
"mcpServers": {
"greenrun": {
"command": "npx",
"args": ["-y", "greenrun-cli@latest"],
"env": { "GREENRUN_API_TOKEN": "${GREENRUN_API_TOKEN}" }
}
}
}
CLI Commands
greenrun init Interactive setup wizard
greenrun update Update templates and commands to latest version
greenrun serve Start MCP server directly
greenrun --version Print version
greenrun --help Print help
Non-interactive init:
npx greenrun-cli init --token gr_xxx --scope local --no-claude-md --no-commands
License
MIT
Server Config
{
"mcpServers": {
"greenrun": {
"command": "npx",
"args": [
"greenrun-cli"
]
}
}
}