Skip to main content
Glama

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.

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

browser_navigate

Open an absolute HTTP or HTTPS URL.

browser_inspect

Detect visible input areas and actions with labels and reusable selectors.

browser_interact

click, type, or scroll an element selected with CSS or XPath.

browser_screenshot

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 chromium

Then start the MCP server:

npx -y mcp-browser-testing-server@latest

The 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 .env
OPENAI_API_KEY=your_openai_api_key
OPENAI_MODEL=gpt-4o-mini

GEMINI_API_KEY=your_gemini_api_key
GEMINI_MODEL=gemini-3.5-flash

Build and start the local Dashboard:

npm run build
npm run dashboard

Open http://127.0.0.1:3210. The Dashboard lets you:

  1. Enter the target website. The QA description is optional.

  2. Select OpenAI or Google Gemini and choose a model.

  3. Verify the API connection before generating content.

  4. Let Playwright map visible fields and actions, then generate validated IT test cases from that context.

  5. Open a target URL in the Playwright-powered browser viewport beside the case list.

  6. Run an individual case and watch the rendered page update after every step.

  7. 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

navigate

Open an HTTP or HTTPS target.

click

Click the first matching element.

type

Fill a field with generated test data.

scroll

Scroll an element into view.

assert_visible

Verify that an element is visible.

assert_text

Verify that an element contains expected text.

screenshot

Capture a page or element screenshot.

Local development

npm install
npx playwright install chromium
npm run typecheck
npm run build
npm start

For development without building first:

npm run dev

Tool 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 assets

The 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 tools
browser_inspectInspect page controlsA

Automatically identify visible input areas, buttons, and links on the current page, including human-readable labels and stable selectors.

NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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.

NameRequiredDescriptionDefault
textNoText to enter. Required only when action is "type".
actionYes
selectorYesCSS selector or XPath selector such as "xpath=//button".

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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_navigateNavigate browserB

Navigate the headless browser to an HTTP or HTTPS URL.

NameRequiredDescriptionDefault
urlYesThe absolute HTTP or HTTPS URL to open.

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It discloses that the browser is headless and restricts URLs to HTTP/HTTPS, but does not describe navigation behavior such as waiting for load, error handling, timeouts, or what the tool returns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no redundant or wasted wording. It communicates the core action efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool, the description covers the essential action. However, with no annotations and no output schema, it omits important behavioral context such as navigation completion, return value, and failure conditions, leaving the definition only minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the single url parameter is already documented in the schema. The description mentions HTTP/HTTPS URLs but adds no syntax or format detail beyond what the schema provides, making the baseline score of 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: navigating a headless browser to a URL. It is clear what the tool does, though it does not explicitly differentiate itself from sibling browser tools such as browser_screenshot or browser_inspect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this tool versus the sibling browser tools, nor any stated prerequisites or exclusions. The intended usage is implied by the name and context, but the description itself provides no comparative guidance.

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.

NameRequiredDescriptionDefault
fullPageNoCapture the full page. Ignored when selector is provided.
selectorNoOptional CSS or XPath selector for an element screenshot.

TDQS

B3.4/5.0
Behavior3/5

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.

Conciseness4/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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.

  1. 4 tool updatesv1.0.0
    • First observedbrowser_inspect
    • First observedbrowser_interact
    • First observedbrowser_navigate
    • First observedbrowser_screenshot

TDQS

A3.5/5.0

Scored across 4 tools

Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness3/5

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

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    C
    quality
    D
    maintenance
    Exposes 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.
    40
    5 npm
    14
    Apache 2.0
  • F
    license
    A
    quality
    C
    maintenance
    Enables 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.
    15
    2
    -
  • A
    license
    Not graded
    quality
    A
    maintenance
    Enables 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.
    12
    Apache 2.0
  • A
    license
    Not graded
    quality
    A
    maintenance
    Enables 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 npm
    MIT