A Model Context Protocol (MCP) server that provides browser automation capabilities using Playwright. This server enables LLMs to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models.
FAST Playwright MCP server
Estrelas
39
Ferramentas
—
Disponibilidade
—
Key Features
Fast and lightweight. Uses Playwright's accessibility tree, not pixel-based input.
LLM-friendly. No vision models needed, operates purely on structured data.
Deterministic tool application. Avoids ambiguity common with screenshot-based approaches.
Fast Server Features (This Fork)
Token Optimization. All tools support an expectation parameter to control response content:
includeCode: false - Suppress Playwright code generation to reduce tokens
browser_execute dispatches schema-validated action and destructive tools.
Known hidden tools remain directly callable for existing integrations.
--tool-profile=full restores the previous complete static catalog.
--tool-profile=minimal exposes only the discovery and dispatch gateways.
The repository enforces a serialized startup budget in CI. Run bun run benchmark:tools -- --check to inspect the current profile sizes.
Security and interoperability controls
The CLI and configuration file support CDP headers and connection timeout, HTTP Host allowlisting, output-directory size limits, response secret redaction, action/navigation/expectation timeouts, a custom test-id attribute, and codegen: "none". The optional offline MCP Apps dashboard is enabled with --caps=apps.
Use the Claude Code CLI to add the Playwright MCP server:
claude mcp add fast-playwright npx @tontoko/fast-playwright-mcp@latest
Follow the MCP install guide, use the standard config above.
Click the button to install:
Or install manually:
Go to Cursor Settings -> MCP -> Add new MCP Server. Name to your liking, use command type with the command npx @tontoko/fast-playwright-mcp@latest. You can also verify config or add command like arguments via clicking Edit.
Follow the MCP install guide, use the standard config above.
Click the button to install:
Or install manually:
Go to Advanced settings -> Extensions -> Add custom extension. Name to your liking, use type STDIO, and set the command to npx @tontoko/fast-playwright-mcp. Click "Add Extension".
Click the button to install:
Or install manually:
Go to Program in the right sidebar -> Install -> Edit mcp.json. Use the standard config above.
Follow the MCP Servers documentation. For example in ~/.config/opencode/opencode.json:
{
/**
* Tool catalog profile. Adaptive is the 0.2 default; full restores the
* pre-0.2 static catalog and minimal exposes only the discovery gateways.
*/
toolProfile?: 'adaptive' | 'full' | 'minimal';
browser?: {
/**
* The browser to use.
*/
browserName?: 'chromium' | 'firefox' | 'webkit';
/**
* Keep the browser profile in memory. By default the profile is written
* under the operating system's temporary Playwright registry directory.
*/
isolated?: boolean;
/**
* Path to the user data directory. Supplying this overrides the generated
* persistent profile location.
*/
userDataDir?: string;
/**
* Launch options passed to Playwright.
*/
launchOptions?: {
channel?: string;
executablePath?: string;
headless?: boolean;
args?: string[];
};
/**
* Browser context options passed to Playwright.
*/
contextOptions?: Record<string, unknown>;
/**
* Existing Chrome DevTools Protocol endpoint.
*/
cdpEndpoint?: string;
/**
* HTTP headers sent when connecting to the CDP endpoint.
*/
cdpHeaders?: Record<string, string>;
/**
* CDP connection timeout in milliseconds.
*/
cdpTimeout?: number;
/**
* Playwright remote browser endpoint.
*/
remoteEndpoint?: string;
};
server?: {
host?: string;
port?: number;
allowedHosts?: string[];
};
capabilities?: Array<'vision' | 'pdf' | 'apps'>;
outputDir?: string;
outputMode?: 'file' | 'stdio';
outputMaxSize?: number;
secrets?: Record<string, string>;
testIdAttribute?: string;
timeouts?: {
action?: number;
navigation?: number;
expect?: number;
};
codegen?: 'typescript' | 'none';
}
User profile
You can run Playwright MCP with a persistent profile, like a regular browser (default), in isolated contexts for testing sessions, or connect to an existing browser using the browser extension.
Persistent profile
All the logged in information will be stored in the persistent profile, you can delete it between sessions if you'd like to clear the offline state.
The persistent profile will be located in the following directories and you can override it with the --user-data-dir argument.
# Windows
%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile
# macOS
- ~/Library/Caches/ms-playwright/mcp-{channel}-profile
# Linux
- ~/.cache/ms-playwright/mcp-{channel}-profile
Isolated
In isolated mode, each session is started in an isolated profile. Every time you ask MCP to close the browser,
the session is closed and all the storage state for this session is lost. Isolated mode can be used for testing
purposes to ensure each session is independent.
The Playwright MCP Browser Extension allows you to connect to existing browser tabs and leverage your current browser session and authenticated state. See the extension/README.md for installation and usage instructions.
Configuration
Playwright MCP server supports following arguments. All of them are optional:
> npx @tontoko/fast-playwright-mcp@latest --help
--allowed-hosts <hosts> comma-separated list of allowed HTTP Host
header values
--allowed-origins <origins> semicolon-separated list of origins to allow
the browser to request. Default is to allow
all.
--blocked-origins <origins> semicolon-separated list of origins to block
the browser from requesting. Blocklist is
evaluated before allowlist.
--block-service-workers block service workers
--browser <browser> browser or chrome channel to use: chrome,
firefox, webkit, or msedge
--caps <caps> comma-separated optional capabilities:
vision, pdf, apps
--cdp-endpoint <endpoint> CDP endpoint to connect to
--cdp-header <header...> CDP request header in Name: Value form; may
be repeated
--cdp-timeout <timeout> CDP connection timeout in milliseconds
--codegen <mode> generated code mode: typescript or none
--config <path> path to the configuration file
--device <device> device to emulate, for example: "iPhone 15"
--executable-path <path> path to the browser executable
--headless run browser in headless mode, headed by
default
--host <host> host to bind server to. Default is localhost.
Use 0.0.0.0 to bind all interfaces.
--ignore-https-errors ignore HTTPS errors
--isolated use an in-memory isolated browser profile
--image-responses <mode> whether image responses are allow or omit
--no-sandbox disable the Chromium sandbox for process
types that normally use it
--output-dir <path> directory for output files
--output-max-size <bytes> maximum output directory size in bytes; zero
disables eviction
--port <port> port to listen on for HTTP transport
--proxy-bypass <bypass> comma-separated domains to bypass the proxy
--proxy-server <proxy> proxy server URL
--save-session save the Playwright MCP session
--save-trace save the Playwright trace
--secrets <path> dotenv file containing values to redact
--storage-state <path> path to storage state for isolated sessions
--test-id-attribute <attribute> attribute used by test-id selectors
--timeout-action <timeout> default action timeout in milliseconds
--timeout-expect <timeout> default expectation timeout in milliseconds
--timeout-navigation <timeout> default navigation timeout in milliseconds
--timeout-settle <timeout> delay after browser actions before capturing
the response, in milliseconds
--tool-profile <profile> tool catalog profile: adaptive, full, or
minimal
--user-agent <ua string> browser user-agent string
--user-data-dir <path> browser user data directory
--viewport-size <size> viewport size as width,height, for example
1280,720
Custom Browser Executables (Firefox Forks and Chrome/Chromium Forks)
By default, Playwright launches its bundled browsers. You can use a custom browser executable (for example a branded Chromium fork or a Firefox-based browser) by specifying the full path to the executable. See CUSTOM_BROWSER_EXECUTABLES.md for detailed, platform-specific instructions and warnings.
CLI: --browser <chromium|firefox|webkit> with --executable-path <full path>
Config file: set browser.launchOptions.executablePath
Important: third-party browser compatibility is not guaranteed. Verify the publisher and binary before use; the server executes the supplied path directly. Waterfox is only an illustrative Firefox-family example and may not support Playwright's required Firefox protocol patches.
Standalone MCP server
When running headed browser on system w/o display or from worker processes of the IDEs,
run the MCP server from environment with the DISPLAY set to a valid X server. For example DISPLAY=:1 npx @tontoko/fast-playwright-mcp@latest --port 8931.
Docker
NOTE: The Docker implementation only supports headless chromium at the moment.
stopOnFirstError (boolean, optional): Stop entire batch on first error
globalExpectation (optional): Default expectation for all steps. Recommended: {includeSnapshot:false,snapshotOptions:{selector:"#app"},diffOptions:{enabled:true}}. Per-step override with steps[].expectation
Read-only: false
browser_click
Title: Perform click on web page
Description: Perform click on web page
Parameters:
selectors (array): Array of element selectors (max 5). Selectors are tried in order until one succeeds (fallback mechanism). Multiple matches trigger an error with candidate list. Supports: ref (highest priority), CSS (#id, .class, tag), role (button, textbox, etc.), text content. Example: [{css: "#submit"}, {role: "button", text: "Submit"}] - tries ID first, falls back to role+text
doubleClick (boolean, optional): Double-click if true
expectation (object, optional): Page state capture config. Use batch_execute for multi-clicks
Read-only: false
browser_close
Title: Close browser
Description: Close the page
Parameters: None
Read-only: false
browser_console_messages
Title: Get console messages
Description: Returns all console messages
Parameters:
consoleOptions (object, optional): undefined
Read-only: true
browser_diagnose
Title: Diagnose page
Description: Analyze page complexity, iframe count, DOM size, modal state, element statistics, and performance characteristics.
Parameters:
searchForElements (object, optional): Search for specific elements and include them in the report
includePerformanceMetrics (boolean, optional): Include performance metrics in the report
includeAccessibilityInfo (boolean, optional): Include accessibility information
includeTroubleshootingSuggestions (boolean, optional): Include troubleshooting suggestions
diagnosticLevel (string, optional): Level of diagnostic detail: none (no diagnostics), basic (critical only), standard (default), detailed (with metrics), full (all info)
useParallelAnalysis (boolean, optional): Use Phase 2 parallel analysis for improved performance and resource monitoring
useUnifiedSystem (boolean, optional): Use Phase 3 unified diagnostic system with enhanced error handling and monitoring
configOverrides (object, optional): Runtime configuration overrides for diagnostic system
includeSystemStats (boolean, optional): Include unified system statistics and health information
expectation (object, optional): undefined
Read-only: true
browser_drag
Title: Drag mouse
Description: Perform drag and drop between two elements
Parameters:
startSelectors (array): Source element selectors for drag start
endSelectors (array): Target element selectors for drag end
expectation (object, optional): Page state after drag. Use batch_execute for workflows
Read-only: false
browser_evaluate
Title: Evaluate JavaScript
Description: Evaluate JavaScript expression on page or element and return result
Parameters:
function (string): JS function: () => {...} or (element) => {...}
selectors (array, optional): Optional element selectors. If provided, function receives element as parameter
expectation (object, optional): Page state config. false for data extraction, true for DOM changes
Read-only: false
browser_file_upload
Title: Upload files
Description: Upload one or multiple files to file input
Parameters:
paths (array): Absolute paths to upload (array)
expectation (object, optional): Page state config. Use batch_execute for click→upload
Read-only: false
browser_find
Title: Find in page snapshot
Description: Search the current accessibility snapshot and return compact matching context.
Parameters:
query (string): undefined
regex (boolean, optional): undefined
caseSensitive (boolean, optional): undefined
maxResults (integer, optional): undefined
contextLines (integer, optional): undefined
expectation (object, optional): undefined
Read-only: true
browser_find_elements
Title: Find elements
Description: Find elements on the page using multiple search criteria such as text, role, tag name, or attributes. Returns matching elements sorted by confidence.
Parameters:
searchCriteria (object): Search criteria for finding elements
maxResults (number, optional): Maximum number of results to return
includeDiagnosticInfo (boolean, optional): Include diagnostic information about the page
useUnifiedSystem (boolean, optional): Use unified diagnostic system for enhanced error handling
enableEnhancedDiscovery (boolean, optional): Enable enhanced element discovery with contextual suggestions
performanceThreshold (number, optional): Performance threshold in milliseconds for element discovery
expectation (object, optional): undefined
Read-only: true
browser_handle_dialog
Title: Handle a dialog
Description: Handle a dialog (alert, confirm, prompt)
Parameters:
accept (boolean): Accept (true) or dismiss (false)
promptText (string, optional): Text for prompt dialogs
expectation (object, optional): Page state after dialog. Use batch_execute for workflows
Read-only: false
browser_hover
Title: Hover mouse
Description: Hover over element on page
Parameters:
selectors (array): Array of element selectors (max 5). Selectors are tried in order until one succeeds (fallback mechanism). Multiple matches trigger an error with candidate list. Supports: ref (highest priority), CSS (#id, .class, tag), role (button, textbox, etc.), text content. Example: [{css: "#submit"}, {role: "button", text: "Submit"}] - tries ID first, falls back to role+text
expectation (object, optional): Page state after hover. Use batch_execute for hover→click
Read-only: false
browser_inspect_html
Title: HTML inspection
Description: Extract filtered HTML with configurable depth, output format, size limits, and automatic truncation.
Parameters:
selectors (array): Array of element selectors to inspect
depth (number, optional): Maximum hierarchy depth to extract
includeStyles (boolean, optional): Include computed CSS styles
maxSize (number, optional): Maximum size in bytes (1KB-500KB)
format (string, optional): Output format
includeAttributes (boolean, optional): Include element attributes
preserveWhitespace (boolean, optional): Preserve whitespace in content
excludeSelector (string, optional): CSS selector to exclude elements
includeSuggestions (boolean, optional): Include CSS selector suggestions in output
includeChildren (boolean, optional): Include child elements in extraction
optimizeForLLM (boolean, optional): Optimize extracted HTML for LLM consumption
expectation (object, optional): Page state config (minimal for HTML inspection)
Read-only: true
browser_navigate
Title: Navigate to a URL
Description: Navigate to a URL
Parameters:
url (string): The URL to navigate to
expectation (object, optional): Page state after navigation
Read-only: false
browser_navigate_back
Title: Go back to previous page
Description: Go back to previous page
Parameters:
expectation (object, optional): Page state after going back
Read-only: false
browser_navigate_forward
Title: Go forward to next page
Description: Go forward to next page
Parameters:
expectation (object, optional): Page state after going forward
Read-only: false
browser_network_requests
Title: List network requests
Description: Returns network requests since loading the page with optional filtering
Parameters:
urlPatterns (array, optional): URL patterns to filter (supports regex)
excludeUrlPatterns (array, optional): URL patterns to exclude (takes precedence)
statusRanges (array, optional): Status code ranges (e.g., [{min:200,max:299}])
methods (array, optional): HTTP methods to filter
maxRequests (number, optional): Max requests to return (default: 20)
newestFirst (boolean, optional): Order by timestamp (default: newest first)
Read-only: true
browser_press_key
Title: Press a key
Description: Press a key on the keyboard
Parameters:
key (string): Key to press
expectation (object, optional): Page state config. Use batch_execute for multiple keys
Read-only: false
browser_resize
Title: Resize browser window
Description: Resize the browser window
Parameters:
width (number): Width of the browser window
height (number): Height of the browser window
expectation (object, optional): undefined
Read-only: false
browser_select_option
Title: Select option
Description: Select option in dropdown
Parameters:
selectors (array): Array of element selectors (max 5). Selectors are tried in order until one succeeds (fallback mechanism). Multiple matches trigger an error with candidate list. Supports: ref (highest priority), CSS (#id, .class, tag), role (button, textbox, etc.), text content. Example: [{css: "#submit"}, {role: "button", text: "Submit"}] - tries ID first, falls back to role+text
values (array): Values to select (array)
expectation (object, optional): Page state after selection. Use batch_execute for forms
Read-only: false
browser_snapshot
Title: Page snapshot
Description: Capture accessibility snapshot of current page
Parameters:
expectation (object, optional): Page state config
Read-only: true
browser_take_screenshot
Title: Take a screenshot
Description: Take a screenshot of current page and return image data
Parameters:
type (string, optional): Image format. When omitted, inferred from filename or defaults to png.
filename (string, optional): File name to save the screenshot to. Defaults to page-{timestamp}.{png|jpeg|webp} if not specified.
selectors (array, optional): Optional element selectors for element screenshots. If not provided, viewport screenshot will be taken.
scale (string, optional): Use CSS pixels or device pixels for the screenshot.
fullPage (boolean, optional): When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Cannot be used with element screenshots.
expectation (object, optional): Additional page state config
Read-only: false
browser_type
Title: Type text
Description: Type text into editable element
Parameters:
selectors (array): Array of element selectors (max 5) supporting ref, role, CSS, or text-based selection
text (string): Text to type into the element
submit (boolean, optional): Press Enter after typing if true
slowly (boolean, optional): Type slowly for auto-complete if true
expectation (object, optional): Page state config. Use batch_execute for forms
Read-only: false
browser_wait_for
Title: Wait for
Description: Wait for text to appear or disappear or a specified time to pass
Parameters:
time (number, optional): Wait time in seconds
text (string, optional): undefined
textGone (string, optional): undefined
expectation (object, optional): Page state after wait
Read-only: true
browser_tab_close
Title: Close a tab
Description: Close a tab by index or close current tab
Parameters:
index (number, optional): Tab index to close (omit for current)
expectation (object, optional): Page state after close
Read-only: false
browser_tab_list
Title: List tabs
Description: List browser tabs with titles and URLs
Parameters:
expectation (object, optional): Page state config
Read-only: true
browser_tab_new
Title: Open a new tab
Description: Open a new tab
Parameters:
url (string, optional): URL for new tab (optional)
expectation (object, optional): Page state of new tab
Read-only: false
browser_tab_select
Title: Select a tab
Description: Select a tab by index
Parameters:
index (number): The index of the tab to select
expectation (object, optional): Page state after tab switch
Read-only: false
browser_install
Title: Install the browser specified in the config
Description: Install the browser specified in the config. Call this if you get an error about the browser not being installed.
Parameters: None
Read-only: false
browser_mouse_click_xy
Title: Click
Description: Click at specific coordinates
Parameters:
element (string): undefined
x (number): X coordinate (requires --caps=vision)
y (number): Y coordinate (requires --caps=vision)
expectation (object, optional): Page state after click. Prefer element ref over coords
Read-only: false
browser_mouse_drag_xy
Title: Drag mouse
Description: Drag from one coordinate to another
Parameters:
element (string): undefined
startX (number): Start X (requires --caps=vision)
startY (number): Start Y (requires --caps=vision)
endX (number): End X
endY (number): End Y
expectation (object, optional): Page state after drag. Prefer element refs over coords
Read-only: false
browser_mouse_move_xy
Title: Move mouse
Description: Move the mouse to coordinates. Requires the vision capability; prefer element-based interactions when possible.
Parameters:
element (string): undefined
x (number): X coordinate
y (number): Y coordinate
expectation (object, optional): undefined
Read-only: false
browser_pdf_save
Title: Save as PDF
Description: Save page as PDF
Parameters:
filename (string, optional): File name to save the pdf to. Defaults to page-{timestamp}.pdf if not specified.
Read-only: false
browser_dashboard
Title: Open browser dashboard
Description: Open the bundled browser preview and tab-selection dashboard.
Parameters: None
Read-only: true
Token Optimization Examples
The Fast Server provides advanced token optimization through expectation controls and batch execution:
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Fast Playwright?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Fast Playwright precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Fast Playwright usa?
Fast Playwright roda localmente via stdio.
Quando Fast Playwright foi verificado pela última vez?
Última verificação: 2026-10-28. FAST Playwright MCP server