mcp-browser-testing-server
Provides AI test-plan generation through the Google GenAI/Gemini API, allowing the Dashboard to select models, verify API connections, and generate structured test cases, with transient-error retry support.
Provides AI test-plan generation through the OpenAI Responses API, allowing the Dashboard to select models, verify API connections, and generate structured test cases from a Playwright page map.
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., "@mcp-browser-testing-serverNavigate to https://example.com/login, sign in as demo@example.com, screenshot dashboard"
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.
mcp-browser-testing-server
An open-source Model Context Protocol (MCP) server that lets AI agents control a headless Chromium browser through Playwright for browser automation, end-to-end testing, screenshots, and debugging.
Legal Disclaimer
This tool is developed and provided exclusively for legitimate automated end-to-end (E2E) testing and academic research. You are responsible for ensuring that every target, account, and dataset you access is authorized and that your use complies with all applicable laws, policies, and third-party Terms of Service.
The authors and contributors are not responsible or liable for misuse of this software, including but not limited to unauthorized scraping, spam, abusive automation, bypassing bot-detection or access-control systems, or any activity that violates a third party's Terms of Service. Do not use this project to evade technical safeguards or to access systems without explicit permission.
For transparency, every browser context automatically uses a User-Agent that contains the project identifier:
Mozilla/5.0 ... (MCP-Browser-Testing-Bot/1.0; OpenSource-Disclaimer-Applied)Related MCP server: orchords-web-pilot
Features
Headless Chromium automation powered by Playwright and its auto-wait behavior.
A persistent browser session shared across MCP tool calls.
Automatic page mapping of visible fields, buttons, and links with labels and stable selectors.
CSS and XPath locator support.
Full-page, viewport, and element screenshots returned directly as MCP image content.
Standard input/output transport for Claude Desktop and other MCP hosts.
Local AI Test Studio UI for asking QA questions and generating structured test cases.
Bilingual English/Vietnamese Dashboard, with English selected by default.
OpenAI and Google Gemini providers with server-side API key support.
Executable test plans with assertions, screenshots, per-step timing, and pass/fail results.
Separate ESM executables for the MCP server and local Dashboard, generated with tsup.
Available tools
Tool | Purpose |
| Open an absolute HTTP or HTTPS URL. |
| Detect visible input areas and actions with labels and reusable selectors. |
|
|
| Capture the full page, viewport, or one selected element as PNG. |
Requirements
Node.js 20 or newer.
A supported Playwright Chromium binary.
An OpenAI API key and/or a Google Gemini API key for AI test-plan generation.
A ChatGPT Plus subscription does not include OpenAI API usage. ChatGPT and the API Platform use separate billing systems. Create and fund an API account at platform.openai.com before using the OpenAI provider.
Install and run with npx
After this package has been published to npm, install the Chromium binary once:
npx playwright install chromiumThen start the MCP server:
npx -y mcp-browser-testing-server@latestThe process communicates through stdio, so it normally appears idle when started directly. An MCP host launches it and exchanges JSON-RPC messages over stdin/stdout.
Claude Desktop configuration
Add the server to claude_desktop_config.json:
{
"mcpServers": {
"browser-testing": {
"command": "npx",
"args": ["-y", "mcp-browser-testing-server@latest"]
}
}
}Restart Claude Desktop after saving the file. On Windows, if Claude Desktop
cannot resolve npx, set command to npx.cmd.
AI Test Studio Dashboard
Copy the environment template and add at least one provider key:
cp .env.example .envOPENAI_API_KEY=your_openai_api_key
OPENAI_MODEL=gpt-4o-mini
GEMINI_API_KEY=your_gemini_api_key
GEMINI_MODEL=gemini-3.5-flashBuild and start the local Dashboard:
npm run build
npm run dashboardOpen http://127.0.0.1:3210. The Dashboard lets you:
Enter the target website. The QA description is optional.
Select OpenAI or Google Gemini and choose a model.
Verify the API connection before generating content.
Let Playwright map visible fields and actions, then generate validated IT test cases from that context.
Open a target URL in the Playwright-powered browser viewport beside the case list.
Run an individual case and watch the rendered page update after every step.
Track running, passed, or failed states in real time, including timing and screenshot evidence.
When a plan is generated, Playwright first inspects the rendered page and sends the AI a compact page map containing visible field labels, placeholders, input types, required/disabled state, actions, and reusable selectors. This means the tester can leave the description empty or provide only a short business goal.
An API key may also be entered temporarily in the Dashboard. A temporary key is sent only to the local loopback backend for the current request and is not saved to local storage or a file. For regular use, environment variables are recommended.
The Dashboard binds to 127.0.0.1 by default. Do not expose it publicly without
adding authentication, TLS, origin controls, and network access restrictions.
Supported generated actions
Action | Behavior |
| Open an HTTP or HTTPS target. |
| Click the first matching element. |
| Fill a field with generated test data. |
| Scroll an element into view. |
| Verify that an element is visible. |
| Verify that an element contains expected text. |
| Capture a page or element screenshot. |
Local development
npm install
npx playwright install chromium
npm run typecheck
npm run build
npm startFor development without building first:
npm run devTool examples
Navigate to a test target:
{
"url": "https://example.com"
}Type into an input:
{
"action": "type",
"selector": "input[name='email']",
"text": "tester@example.com"
}Capture a selected element:
{
"selector": "main"
}Playwright accepts CSS selectors by default. Prefix XPath selectors with
xpath=, for example xpath=//button[@type='submit'].
Architecture
src/index.ts MCP transport and core MCP tools
src/dashboard.ts Local Dashboard HTTP server and API routes
src/browser.ts Playwright lifecycle and browser operations
src/test-runner.ts Structured test-case execution engine
src/domain/test-case.ts Shared Zod schemas and domain types
src/ai/provider.ts AI provider abstraction and provider factory
src/ai/openai-provider.ts OpenAI Responses API adapter
src/ai/gemini-provider.ts Google GenAI adapter with transient-error retry
web/ Browser UI assetsThe MCP layer depends on the BrowserController abstraction, while all browser
lifecycle and interaction details remain isolated in src/browser.ts. Chromium
starts lazily on the first browser tool call and closes on SIGINT or SIGTERM.
Build output
npm run build creates two executable entry points:
dist/index.js— the stdio MCP server.dist/dashboard.js— the local AI Test Studio.
The MCP SDK and schema validation code are bundled. Playwright remains a runtime dependency because its browser binaries and executable discovery are managed separately.
License
Released under the MIT License.
Available Tools
4 toolsbrowser_inspectInspect page controlsA
Automatically identify visible input areas, buttons, and links on the current page, including human-readable labels and stable selectors.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries full behavioral burden. It does disclose meaningful traits: only *visible* elements are returned, and results include human-readable labels plus stable selectors that can be reused for interaction. It does not state that the tool is side-effect-free, what happens on a page that hasn't loaded, or whether iframes/shadow DOM are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; every clause (visible, input areas/buttons/links, labels, selectors) carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must convey the return shape, and it only partially does (labels and selectors). For a zero-param inspection tool with no annotations and no output schema, it should disclose whether results are a flat list, whether hidden/disabled controls are excluded, and whether the selectors are guaranteed reusable with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so per the baseline this scores 4. The description correctly reflects that no scoping input is required—inspection applies to the page as-is.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action (identify) and specific resources (visible input areas, buttons, links) scoped to the current page. This differentiates it from browser_screenshot and browser_navigate by being a discovery/inspection operation, though it never explicitly contrasts itself with browser_interact, which also targets page controls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"On the current page" implies a prerequisite that navigation must happen first, and the read-only framing hints this precedes interaction. However, there is no explicit statement of when to use this versus browser_interact, nor any exclusion of cases (e.g., after DOM changes, on non-HTML pages). Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
browser_interactInteract with browserC
Click, type into, or scroll an element into view using a CSS or XPath selector.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Text to enter. Required only when action is "type". | |
| action | Yes | ||
| selector | Yes | CSS selector or XPath selector such as "xpath=//button". |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden but discloses almost nothing: it doesn't say whether click waits for element readiness, whether typing appends or replaces text, what errors look like on missing elements, or what is returned. It does clarify that scroll brings an element into view rather than scrolling the page arbitrarily, which is a small useful addition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no wasted words. It is efficiently sized, though it is under-specified rather than richly informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a side-effecting interaction tool with no annotations and no output schema, the description is too thin: preconditions, failure behavior, and interaction semantics are all missing. Only the selector format and basic action set are conveyed, and mostly via the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% and the schema already documents the action enum, the text parameter's conditionality, and selector format. The description merely restates the action enum values and never mentions the text parameter, so it adds no meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States specific verbs (click, type, scroll) and resource (element via CSS/XPath selector), which clearly separates it from navigate/screenshot/inspect siblings. It doesn't explicitly name or contrast with those siblings, so not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus browser_navigate or browser_inspect, and no preconditions such as requiring a page to be loaded first. The only implied usage is that a selector must exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
browser_screenshotCapture screenshotB
Capture a PNG screenshot of the whole page, viewport, or a selected element.
| Name | Required | Description | Default |
|---|---|---|---|
| fullPage | No | Capture the full page. Ignored when selector is provided. | |
| selector | No | Optional CSS or XPath selector for an element screenshot. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the output format (PNG) and the capture modes. However it never says what the tool actually returns (raw image content vs. a path/URL) or whether navigating first is a prerequisite, which are the details an agent most needs here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler, and the resource plus scope options come first. It is efficient, though efficiency shades into under-specification here.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A simple two-parameter tool, but with no annotations and no output schema the description should still cover the return shape and any precondition such as an active page. It covers the what but not the how or the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema itself explains the fullPage/selector interaction, so the description adds no meaning beyond it. The phrase 'whole page, viewport, or a selected element' merely restates the parameter set; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (capture a PNG screenshot) and enumerates the three capture scopes that map to the parameters. It does not explicitly contrast with siblings browser_inspect or browser_interact, but the purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the tool's nature; there is no statement of when to prefer a screenshot over browser_inspect or browser_interact, and no note that the page must already be navigated to. An agent can infer the use case, but nothing is spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
4 tool updates
v1.0.0- First observed
browser_inspect - First observed
browser_interact - First observed
browser_navigate - First observed
browser_screenshot
TDQS
Scored across 4 tools
Each tool maps to a distinct browser action: navigation, inspection, interaction, and screenshot capture. There is no meaningful overlap between inspecting elements and interacting with them, since one discovers selectors and the other acts on them.
All tools use the same browser_ prefix followed by a concise action-oriented name. browser_screenshot uses a noun form, but it is conventionally understood as an action and does not break the overall pattern.
Four tools is well within the ideal range and each tool has a clear role in the core browser testing loop. The surface is compact without feeling arbitrarily truncated.
The core workflow of navigate, inspect, interact, and screenshot is covered, but important browser-testing operations are missing, such as waiting for elements or page load, extracting text, capturing console/network errors, and closing the browser session. These gaps could cause flaky automation or dead ends.
Maintenance
Related MCP Connectors
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Related MCP Servers
- AlicenseCqualityDmaintenanceExposes a remote browser as MCP tools via Playwright, enabling AI agents to navigate and interact with web pages through DOM snapshots, clicks, typing, and form operations.405 npm14Apache 2.0

orchords-web-pilotofficial
FlicenseAqualityCmaintenanceEnables coding agents to drive a real Playwright-backed browser session, navigating, observing, interacting, and capturing proof on web pages via MCP tools across stdio and Streamable HTTP transports.152-- AlicenseNot gradedqualityAmaintenanceEnables browser automation through MCP with native Playwright operations, deterministic assertions, and natural-language grounded actions, structured extraction, and bounded agent workflows over live page elements.12Apache 2.0
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to drive real Chromium, WebKit, or Firefox browsers — opening named sessions, running ordered steps like clicks, typing, and assertions, and reading back text, console/network logs, and screenshots — so web apps can be tested and explored end to end. It starts and shares dev servers, attaches to already-running browsers, and can fake API responses or device settings.1 npmMIT