wopee-mcp
OfficialAn MCP server that connects AI agents (Claude, Cursor, etc.) to Wopee.io so they can generate, run, and report on autonomous tests.
Inspect tests: read test inventory with counts/statuses (incl. never-run), list analysis suites, fetch recent and per-analysis execution results, and read agent/code reports.
Build suites and artifacts: create blank suites, dispatch an AI crawl analysis to auto-generate tests, and generate/read/replace artifacts (app context, user stories, test cases, steps, Playwright code).
Run tests: dispatch the autonomous testing agent on selected test cases (async) and poll for verdicts.
Manage variables: read and upsert run-time variables at project or analysis level (merge, no delete).
Report and collaborate: file GitHub issues with run evidence (failing step, screenshot, link), plus send/read project chat messages (Commander-only).
Support: verify setup/connection, and search the Wopee.io docs without needing an API key.
Provides tools to fetch and update application context, project context, and general user stories in Markdown format.
Wopee.io MCP Server
AI-powered autonomous testing for your apps -- connect Claude, Cursor, or any MCP-compatible AI agent to Wopee.io and generate test cases, user stories, and run autonomous tests in seconds.
Requirements
Node.js 20.18 or newer (Node.js 22 recommended). The server runs with
npx; there is nothing else to install.A Wopee.io project with an API key. In Commander, open the project and go to More › Settings › API Keys; the same screen shows the project UUID. See API keys.
Related MCP server: Playwright MCP
Setup
Per-client guides (Claude Code, Cursor, VS Code, Codex and more): docs.wopee.io/guides/wopee-mcp.
npx -y @wopee-io/init sets all of this up in a repo: it writes a git-ignored .env and the entries below for each agent you pick.
1. Put the credentials in the repo's .env
WOPEE_API_KEY=your-api-key
WOPEE_PROJECT_UUID=your-project-uuidMake sure git ignores the file (git check-ignore .env). The server reads .env.local and .env from the client's workspace folder (or the folder it starts in), so no MCP config needs the key and every config below is safe to commit.
2. Add the server, without a key
Client | File | Entry |
Claude Code |
|
|
Cursor |
|
|
VS Code |
|
|
OpenCode |
|
|
Codex reads project config only in trusted projects, so add the server to ~/.codex/config.toml:
[mcp_servers.wopee]
command = "npx"
args = ["-y", "wopee-mcp"]Keep
commandandargsas separate fields. Clients start the server without a shell, so"command": "npx wopee-mcp"in one string does not work everywhere.On native Windows (not WSL), Claude Code needs
cmd /cin front ofnpx:"command": "cmd", "args": ["/c", "npx", "-y", "wopee-mcp"].Values in the MCP process environment still win, so existing configs with
envblocks or${VAR}references keep working.
Where the server looks
Each value comes from the first place that has it; an empty value counts as unset:
The MCP process environment.
The file named by
WOPEE_ENV_FILE(relative paths are read from the workspace folder)..env.local, then.env, in each workspace folder the client reports (MCP roots), then in the folder the server starts in.~/.config/wopee/credentials.json(or underXDG_CONFIG_HOME):{ "default": "<project-uuid>", "projects": { "<project-uuid>": { "apiKey": "…", "apiUrl": "…" } } }.
The files are read on every call, so a tool works as soon as .env is in place, with no restart. Without credentials, tools return an error telling the agent to run npx -y @wopee-io/init. The server never prints the key.
Environment variables
Variable | Required | Description |
| yes | Project API key from More › Settings › API Keys |
| yes | The project the server works with. Every tool uses it |
| no | Only for a dedicated or self-hosted Wopee.io instance; copy it from the API Keys screen. Defaults to |
| no | Path to an env file to read before the workspace |
| no | Corporate proxy, see below |
| no | PEM file with your company's root certificate, see below |
Verify the connection
Your client should list the wopee server with 17 tools starting with wopee_ (/mcp in Claude Code). Then ask:
How many tests do I have in Wopee.io, and which ones have never run?The agent calls the read-only wopee_fetch_test_inventory. A new project returns zero tests; continue with an analysis (wopee_dispatch_analysis).
Tools
All tools except wopee_search_docs work in the project set by WOPEE_PROJECT_UUID. Write tools change data in your project; let your agent ask before it calls them.
Tool | What it does | Access | Timing |
| Counts tests per analysis with the latest status of each, including never-run ones ( | read | seconds |
| Lists analysis suites with their UUIDs, identifiers ( | read | seconds |
| Creates an empty analysis suite for tests you write or generate yourself | write | seconds |
| Creates a suite and starts the crawl that explores the app and generates tests. Optional instructions, variables, rerun of an existing analysis | write | async, minutes |
| Starts the testing agent on chosen test cases of an analysis. Returns run handles, not results | write | async, minutes |
| The 20 newest runs in the project with verdict or status and a short report | read | seconds |
| Full results of the runs of one analysis, with the agent's report | read | seconds |
| Reads | read | seconds |
| Replaces one of those artifacts with content from the agent (whole file, not a patch) | write | seconds |
| Generates app context, user stories, test cases or steps with Wopee.io's AI | write | up to 5 min; |
| Checks the connection: project, app URL, plan, steps left and Commander link; names a wrong key or missing UUID | read | seconds |
| Reads run-time variables at project or analysis level | read | seconds |
| Adds or overwrites run-time variables (merge, no delete) | write | seconds |
| Files a GitHub issue in the project's connected repository, with run evidence when given a run UUID | write | seconds |
| Posts to the project chat. Offered only inside the Commander Assistant, never with a project API key or over the remote server | write | seconds |
| Reads the project chat. Offered only inside the Commander Assistant, never with a project API key or over the remote server | read | seconds |
| Searches the Wopee.io docs (docs.wopee.io) and returns the best matching sections with their page URL. Needs no API key or project; cached for an hour | read | seconds |
wopee_generate_artifact types: APP_CONTEXT, GENERAL_USER_STORIES, USER_STORIES_WITH_TEST_CASES, TEST_CASES, TEST_CASE_STEPS, REUSABLE_TEST_CASES, REUSABLE_TEST_CASE_STEPS. Generate in that order. USER_STORIES_WITH_TEST_CASES rebuilds every user story and test case of the suite, and TEST_CASES with mode: CREATE replaces test cases with their run history; use them on an existing suite only when you mean it.
Parameters and examples for each tool: Tools reference.
Prompts
Three MCP prompts. In Claude Code they appear as slash commands, for example /mcp__wopee__run-test.
Prompt | What the agent does |
| Lists your suites, user stories and test cases as two tables |
| Lists the latest results per suite, with a section for failed reports |
| Finds the test case that matches your request, asks "Run this test? (yes/no)", starts it and fetches the result. If nothing matches, offers a full analysis or a quick single test |
Typical workflow
See what you have:
wopee_fetch_test_inventory(read-only), thenwopee_fetch_analysis_suitesfor suite UUIDs and analysis identifiers.No tests yet?
wopee_dispatch_analysiscrawls the app from the project's starting URL and generates user stories and test cases. Pollwopee_fetch_analysis_suitesuntil it finishes (several minutes). Or create a blank suite withwopee_create_blank_suiteand fill it withwopee_update_artifact/wopee_generate_artifact.Run tests:
wopee_dispatch_agentwith the analysis suite UUID, analysis identifier and test cases. It returns at once with run handles, not the verdict.Read the verdict: poll
wopee_fetch_recent_executionsorwopee_fetch_executed_test_casesevery 30-60 s until the run is finished, then read the agent report.Report failures:
wopee_create_github_issuewith the failed run'sexecutedTestCaseUuidfiles it with the failing step, screenshot and a link to the run.
Good to know:
Your app must be reachable from Wopee.io. Tests run in the cloud, so
localhostdoes not work; use a public or staging URL.Usage counts. Runs started through MCP count toward the plan of the user who created the API key. When the limit is reached, calls return
[USAGE_LIMIT_EXCEEDED]with the time the limit resets.10 seconds between dispatches per project; the server retries automatically after a rate-limit answer.
Commander shows the generated tests and every run visually.
Running it as a remote (HTTP) server
wopee-mcp-http serves the same tools over Streamable HTTP for a Wopee.io instance that runs it next to its api. It is an OAuth resource server: clients add it by its URL alone, and the instance's api signs them in (/oauth/*). Nothing about a caller comes from the server's own environment or files; every request carries the caller's token, and the api checks it.
MCP_RESOURCE_URL=https://mcp.example.com/mcp WOPEE_AUTHORIZATION_SERVER=https://api.example.com WOPEE_API_URL=http://api:4000 PORT=8080 npx -y -p wopee-mcp wopee-mcp-httpVariable | What it is |
| The public URL of the MCP endpoint. Tokens are issued for exactly this URL. |
| The api's public URL, its OAuth issuer. |
| Where the server sends its api requests; defaults to |
| Defaults to |
POST /mcp(the path ofMCP_RESOURCE_URL): stateless JSON responses. Without a validAuthorization: Bearerit answers401with aWWW-Authenticatethat points at/.well-known/oauth-protected-resource/mcp(RFC 9728).Headless clients (
claude -p, the Agent SDK, CI) can send a project API key as the bearer token instead of signing in.A read-only connection lists only the tools that read. Calling a tool that writes answers
403witherror="insufficient_scope".One JSON-RPC message per request. Requests with an
Originother than the server's own are refused.GET /healthzfor the container's health check.
Corporate proxy
Behind a corporate proxy or VPN, set the standard proxy variables in the server's env:
"env": {
"WOPEE_API_KEY": "your-api-key",
"WOPEE_PROJECT_UUID": "your-project-uuid",
"HTTPS_PROXY": "http://your-proxy-server:8080"
}HTTPS_PROXY (or https_proxy) is checked first, then HTTP_PROXY (or http_proxy). Your VS Code http.proxy setting or your IT department has the value, for example http://proxy.company.com:8080 or http://username:password@proxy.company.com:8080.
TLS and certificates
Errors such as UNABLE_TO_VERIFY_LEAF_SIGNATURE or self-signed certificate in certificate chain mean Node does not trust a certificate on the way: usually a corporate proxy that inspects TLS, or a self-hosted instance with an internal CA. Point Node at your company's root certificate:
"env": {
"WOPEE_API_KEY": "your-api-key",
"WOPEE_PROJECT_UUID": "your-project-uuid",
"NODE_EXTRA_CA_CERTS": "/path/to/company-root-ca.pem"
}Do not switch TLS verification off. More fixes: Troubleshooting.
Available Tools
15 toolswopee_create_blank_suiteCreate blank analysis suiteA
Create a new empty analysis suite in the current project. Use this as the first step when you want to manually build a test suite — the returned suite UUID is needed by wopee_generate_artifact, wopee_fetch_artifact, wopee_update_artifact, and wopee_dispatch_agent. If you want to auto-analyze a web app instead, use wopee_dispatch_analysis which creates and populates a suite in one step. Takes no input parameters; uses WOPEE_PROJECT_UUID from environment. Not idempotent: each call creates a new suite. Returns the suite object with UUID, name, type, and status. Fails if WOPEE_PROJECT_UUID is not configured.
Inputs: no named parameters.
wopee_create_github_issueCreate GitHub issueA
Create a new GitHub issue in the project's connected repository. Use this to report bugs found during testing, track test failures, or create action items from chat discussions. For a failed test, pass its executedTestCaseUuid so the issue carries the run's evidence (failing step, expected vs actual, screenshot, report link). The issue is created by the Wopee.io GitHub App and names the requester in its body. Requires a GitHub repository linked to the project and WOPEE_PROJECT_UUID to be set.
Inputs: title (required), body, labels, executedTestCaseUuid.
wopee_dispatch_agentDispatch autonomous testing agentA
Dispatch an autonomous AI agent to execute specific test cases. The agent opens a real browser, navigates the app, follows the test case's steps, and reports results. A test case without steps runs as it is: the agent follows its description and the run records the steps it took, so never generate steps first just to be able to run it. Tests run ASYNCHRONOUSLY (1-3 minutes). This tool returns tracking info confirming dispatch — NOT final results. Do NOT interpret the response as pass/fail. Poll wopee_fetch_recent_executions or wopee_fetch_executed_test_cases every 30-60 s for the verdict (inside the Commander Assistant, results also arrive as a chat notification). Prerequisite: test cases must exist in the suite (generate with wopee_generate_artifact type USER_STORIES_WITH_TEST_CASES).
Inputs: suiteUuid (required), testCases (required), analysisIdentifier (required).
wopee_dispatch_analysisDispatch analysis crawlA
Create a new analysis suite AND dispatch an AI crawling agent in one step. The agent opens a real browser, navigates from the starting URL, discovers pages, and maps the application structure. Use this when you want to auto-analyze a web app — it combines suite creation and crawling. Use wopee_create_blank_suite instead if you want to manually populate the suite. The crawl starts from the starting URL set in the project settings in Commander; this tool has no starting URL, login or cookie inputs. Optional inputs: free-text instructions to guide the crawl, custom variables (e.g. login details the instructions refer to), and a rerun of an existing suite. Not idempotent: each call creates a new suite and starts a new crawl. Side effects: creates a suite and execution records on the platform. Rate limit: 10 seconds between dispatches per project; concurrent calls auto-retry with exponential backoff. Returns the suite UUID, analysis identifier and status; poll wopee_fetch_analysis_suites every 30-60 s to follow it (5-10 minutes).
Inputs: rerun, additionalVariables, additionalInstructions.
wopee_fetch_analysis_suitesList analysis suitesARead-onlyIdempotent
List all analysis suites in the current project. Returns an array of suite objects with UUIDs, names, types (ANALYSIS, AGENT, etc.), and running statuses (IDLE, IN_PROGRESS, FINISHED). Use this to discover existing suites before calling other tools — you need a suite UUID for wopee_generate_artifact, wopee_fetch_artifact, wopee_update_artifact, and wopee_dispatch_agent. Read-only: does not create or modify anything. Takes no input; works in the connected project. Returns an empty array if no suites exist.
Inputs: no named parameters.
wopee_fetch_artifactFetch test artifactsARead-onlyIdempotent
Retrieve a specific test artifact from a suite. Returns the artifact content as text. Use this to review what wopee_generate_artifact created, or to retrieve existing artifacts before editing with wopee_update_artifact. Does NOT modify any data — this is a read-only operation. If the requested artifact type has not been generated yet for this suite, returns an empty result. For PLAYWRIGHT_CODE, you must provide the test case identifier (e.g. 'US004:TC006'); omitting it returns an error. For all other types, the identifier parameter is ignored.
Inputs: type (required), suiteUuid (required), identifier.
wopee_fetch_executed_test_casesFetch test execution resultsARead-onlyIdempotent
Retrieve results of test cases executed by the autonomous agent. Returns each test case with its execution status (IN_PROGRESS, FINISHED, FAILED), agent report (natural language findings), and code report (technical details). Read-only: does not trigger any execution. Use this after wopee_dispatch_agent to check results — if status is IN_PROGRESS, wait and call again. Requires suite UUID. Optionally accepts an analysis identifier (e.g. A068, found in suite data) to filter to a specific analysis run. Returns an empty array if no test cases have been executed in this suite. Do NOT use this to fetch test artifacts like user stories or code — use wopee_fetch_artifact for that.
Inputs: suiteUuid (required), analysisIdentifier.
wopee_fetch_recent_executionsFetch recent test executionsARead-onlyIdempotent
Fetch the most recent test case executions for the current project (up to 20, newest first). Use this to check the status of recently dispatched tests without needing to remember specific suite UUIDs. Returns each run's verdict (PASSED, FAILED, or INCOMPLETE — the run never established a result, e.g. an infrastructure error, and says nothing about the application) or, for a run with no verdict yet, its execution status (IN_QUEUE, IN_PROGRESS, FINISHED, FAILED, STOPPED), plus agent reports. Takes no input; uses WOPEE_PROJECT_UUID from environment. Prefer this tool when the user asks 'what's the status?' or 'how did the tests go?' and you don't have the specific suite UUID handy.
Inputs: no named parameters.
wopee_fetch_test_inventoryFetch test inventory (counts + statuses)ARead-onlyIdempotent
The authoritative tool for how many tests exist and their latest status. Returns, per analysis, the FULL list of authored test cases joined with their latest execution status — including never-run ones as NOT_RUN. Use this for questions like 'how many tests do I have', 'list the scenarios/test cases in A001', or 'show executed and not-run tests in one table'. Terminology: a 'scenario' is a test case; test cases are grouped under user stories (US001) and identified as US001:TC001. Reusable blocks (user story R001) are counted separately (reusableBlockCount) and are building blocks, not runnable, so they never carry an execution status. Regular tests are all non-R001 test cases. Read-only. Takes an optional analysisIdentifier (e.g. A001) to scope to one analysis; omit to cover every analysis in the project. Prefer this over wopee_fetch_recent_executions / wopee_fetch_executed_test_cases when the user asks about totals or the complete list — those return only test cases that have already run. Each test case carries executedTestCaseUuid (the latest run's uuid, the same one wopee_dispatch_agent returns) and verdictGateDisagreed (true when a verdict gate disagreed with a PASSED verdict — report it alongside the pass). Status UNKNOWN means the execution history could not be read (the reason is in the analysis's executionHistoryError); do not report such tests as not run.
Inputs: analysisIdentifier.
wopee_fetch_variablesFetch run-time variablesARead-onlyIdempotent
Read the run-time variables (additionalVariables) that drive analysis/agent runs, at either level. level: PROJECT returns the project-level variables (the connected project); level: ANALYSIS returns a specific analysis suite's variables and requires suiteUuid, including the analysis' own TESTING_USERNAME, TESTING_PASSWORD, WOPEE_DEVICE and WOPEE_BROWSER when its settings set them; each overrides the project variable of the same key for that analysis. Read-only. Returns a JSON string array of { key, value, sourceType } entries, or [] when none are set; secret values (e.g. passwords) read as "***". Use wopee_fetch_analysis_suites to discover suite UUIDs.
Inputs: level (required), suiteUuid.
wopee_generate_artifactGenerate test artifactsADestructive
Generate AI-powered test artifacts for a suite using the Wopee.io AI engine. Each call creates one artifact type — call multiple times for different types. Generation order matters: APP_CONTEXT must be generated before user stories, and user stories before test cases. If called out of order, the AI may produce lower quality results. By default the call waits up to 5 minutes for the generation and returns the generated artifact: APP_CONTEXT or GENERAL_USER_STORIES, or the suite's USER_STORIES (stories with their test cases and steps) for every other type. No wopee_fetch_artifact call is needed after it. With async: true, for TEST_CASES and USER_STORIES_WITH_TEST_CASES only, the call returns "Queued: …" at once; read the result later with wopee_fetch_artifact. If the 5 minutes pass first, the call fails with a [TIMEOUT] error while the generation goes on: do not call again (that starts a second generation), read the result later with wopee_fetch_artifact, and pass async: true next time for a long TEST_CASES or USER_STORIES_WITH_TEST_CASES generation. Do NOT use this to hand-edit existing artifacts — use wopee_update_artifact instead. TEST_CASES runs in UPDATE mode by default: existing test cases keep their steps and run history, and instructions says what to add or change. Destructive generations are mode CREATE (replaces the test cases in scope and deletes their steps, runs and code), USER_STORIES_WITH_TEST_CASES (rebuilds every story and test case) and TEST_CASE_STEPS (replaces the steps of the test cases in scope): use them only when the user explicitly asks for that, and scope them with selectedUserStories / selectedTestCases when the user named stories or test cases. Login credentials are project variables, referenced in steps as ${TESTING_USERNAME} / ${TESTING_PASSWORD}: check which exist with wopee_fetch_variables and set missing ones with wopee_update_variables before generating. Never put a password or other secret value in instructions — it would be copied into the artifact.
Inputs: type (required), suiteUuid (required), mode, async, +3 more.
wopee_search_docsSearch the Wopee.io docsARead-onlyIdempotent
Search the Wopee.io documentation (docs.wopee.io, from its llms-full.txt) and return the best matching sections with their page URL. Use it for questions about setup, configuration, environment variables, integrations (Playwright, Cypress, WebdriverIO, Robot Framework), MCP clients, CI, concepts and troubleshooting, before guessing. Read-only, needs no API key, and does not touch the project. Results are cached for an hour.
Inputs: query (required), maxResults.
wopee_setup_checkCheck the setupARead-onlyIdempotent
Verify that Wopee.io is connected: returns the project name and UUID, app URL, plan, steps left, reset time and the Commander link for the project of WOPEE_API_KEY, and names the problem when the key belongs to another project than WOPEE_PROJECT_UUID, the UUID is missing or the key is rejected. Read-only, takes no input. Call it as the last step of a setup and whenever a tool answers Not Authorised!.
Inputs: no named parameters.
wopee_update_artifactUpdate test artifactsADestructiveIdempotent
Create or overwrite a test artifact in a suite with caller-supplied content. The full content is replaced, not patched. Use this to upload your own APP_CONTEXT (e.g. built from JIRA / Confluence), user stories, project context, or Playwright code, or to fix / refine an artifact previously authored by wopee_generate_artifact. Works on any suite, including freshly-created blank suites with no prior generation — the artifact does not need to exist beforehand. Use wopee_generate_artifact instead when you want the Wopee.io AI engine to author the content from scratch. On success, returns confirmation. On failure (e.g. invalid suite UUID, storage misconfiguration), returns an error message. Idempotent: calling with the same content multiple times produces the same result.
Inputs: type (required), content (required), suiteUuid (required), identifier.
wopee_update_variablesUpdate run-time variablesADestructiveIdempotent
Upsert the run-time variables (additionalVariables) that drive analysis/agent runs, at either level. level: PROJECT writes the project-level variables (the connected project); level: ANALYSIS writes a specific analysis suite's variables and requires suiteUuid. Merge semantics: keys in variables[] are added or overwritten, existing keys not listed are preserved. Keys must be uppercase (e.g. BASE_URL); the server re-sanitizes and drops invalid keys. Returns a confirmation on success.
Inputs: level (required), variables (required), suiteUuid.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools target a distinct action (create vs dispatch vs generate vs fetch vs update), and the descriptions explicitly cross-reference each other to steer selection. The one soft spot is the cluster of result-reading tools (wopee_fetch_executed_test_cases, wopee_fetch_recent_executions, wopee_fetch_test_inventory), which overlap in purpose, though the 'prefer this when…' guidance largely resolves which to pick.
Every tool follows the same wopee_<verb>_<noun> pattern (create_blank_suite, fetch_analysis_suites, dispatch_agent, update_variables, generate_artifact), making the action and resource readable at a glance. The only minor deviation is wopee_setup_check, which is a noun phrase rather than a verb_object, but it does not break the pattern.
15 tools is squarely in the well-scoped range for a platform covering suites, artifacts, runs, variables, docs, and GitHub reporting. Each tool maps to a concrete operation in the workflow with no obviously redundant entries.
The lifecycle is well covered end to end: connectivity check, suite discovery/creation, artifact generate/read/update, dispatch, polling for results, variables, and issue reporting. Gaps are around cleanup and control — no delete/archive for suites or artifacts and no cancel/stop for a dispatched run — which agents can work around but leaves the surface slightly short of full CRUD.
Maintenance
Related MCP Connectors
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
MCP server for Mint — AI-powered QA that runs your app in a real browser on every PR.
Hosted Web Crawler MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
AlicenseBqualityAmaintenancePostman’s remote MCP server connects AI agents, assistants, and chatbots directly to your APIs on Postman. Use natural language to prompt AI to automate work across your Postman collections, environments, workspaces, and more.426,438 npm329Apache 2.0- AlicenseAqualityNot gradedmaintenanceEnables browser automation through Playwright using accessibility tree snapshots instead of screenshots. Supports web scraping, form interactions, testing, and connecting to existing browser sessions with logged-in accounts.238,303 npm5-
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI-powered browser automation, web scraping, and testing using Playwright across Chromium, Firefox, and WebKit. It allows users to perform actions like navigation, clicking, typing, and taking screenshots through natural language interfaces.MIT
- AlicenseNot gradedqualityBmaintenanceAI-powered E2E testing MCP server. Point at a URL — AI generates test scenarios, runs Playwright tests, and self-heals failures automatically. Works on Canvas and Flutter Web apps.164 PyPI7AGPL 3.0