Browser Instrumentation MCP Server
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., "@Browser Instrumentation MCP Server navigate to news.ycombinator.com and show me the console logs"
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.
Browser Instrumentation MCP Server
A Model Context Protocol (MCP) server for browser instrumentation using Playwright. Prioritizes observation over action.
This server does not attempt to make browser automation reliable. Browsers are non-deterministic systems. This server prioritizes visibility over convenience.
Philosophy
This server is designed around one principle: observation first, action second.
INSPECT tools (7 tools) - Safe, encouraged, no side effects
ACT tools (3 tools) - Dangerous, require escalation and justification, logged
Actions don't return success/failure. They return what was observed with a confidence level.
When NOT to Use This
Form filling
Login automation
Payment flows
Anything you wouldn't trust a flaky intern to do
Any scenario requiring reliable, repeatable automation
If you need reliable automation, use Playwright directly with proper test infrastructure.
Installation
Prerequisites
Python 3.11 or later
Playwright browsers installed
Install from source
git clone https://github.com/yourusername/browser-instrumentation-mcp.git
cd browser-instrumentation-mcp
pip install -e .
playwright install chromiumConfiguration
Claude Desktop
Add to your Claude Desktop configuration:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"browser": {
"command": "python",
"args": ["-m", "browser_instrumentation_mcp.server"]
}
}
}Claude Code
claude mcp add browser -- python -m browser_instrumentation_mcp.serverAvailable Tools
Session Management
Tool | Description |
| Create a new session (observation-only mode) |
| List sessions with status and event count |
| Clean up session |
| Enable actions (requires reason) |
INSPECT Tools (Safe)
Tool | Description |
| Navigate to URL |
| Capture page screenshot |
| Get HTML content |
| Get text content (no HTML) |
| Get console log messages |
| Get network requests |
| Get session event log |
ACT Tools (Require Escalation)
Tool | Description |
| Click element (requires reason) |
| Type into input (requires reason) |
| Execute JavaScript (requires reason) |
Usage Examples
Observation workflow (typical)
1. browser_session_create(name="research")
2. browser_inspect_navigate(session="research", url="example.com")
3. browser_inspect_screenshot(session="research")
4. browser_inspect_text(session="research")
5. browser_inspect_events(session="research") # audit what happened
6. browser_session_destroy(name="research")Action workflow (when observation isn't enough)
1. browser_session_create(name="test")
2. browser_inspect_navigate(session="test", url="example.com")
3. browser_session_escalate(name="test", reason="need to test form submission")
4. browser_act_click(session="test", selector="button", reason="testing submit button")
# Returns observed changes, NOT success/failure
5. browser_inspect_events(session="test") # see what was logged
6. browser_session_destroy(name="test")Action result format
ACT tools return observed changes, not success/failure:
Action: click
Confidence: medium
Observed Changes:
URL changed: true
Network requests: 3
Console messages: 0
New URL: https://example.com/submitted
State:
Before: https://example.com/form
After: https://example.com/submittedEvent Log
Every session maintains an append-only event log. Use browser_inspect_events to audit what happened:
[
{"event_type": "session_created", "timestamp": "...", "details": {...}},
{"event_type": "navigate", "timestamp": "...", "details": {"url": "..."}},
{"event_type": "session_escalated", "reason": "testing form", ...},
{"event_type": "click", "reason": "submit button", "details": {...}}
]Architecture
browser_instrumentation_mcp/
├── server.py # FastMCP server with INSPECT/ACT tools
├── browser_manager.py # Session lifecycle management
├── models.py # Pydantic models (EventLog, ActionResult, etc.)
├── backends/
│ ├── base.py # Abstract backend interface
│ └── playwright_backend.py # Playwright implementationDevelopment Setup
git clone https://github.com/yourusername/browser-instrumentation-mcp.git
cd browser-instrumentation-mcp
pip install -e .[dev]
playwright install chromium
# Run directly
python -m browser_instrumentation_mcp.serverTesting
# Unit tests only (fast, no browser required)
pytest -m "not integration"
# All tests (includes real browser and CDP integration tests)
pytestIntegration tests are marked with @pytest.mark.integration and may require:
Playwright browsers installed (
playwright install chromium)Network access for real navigation
A running CDP-enabled browser for CDP tests
To run CDP integration tests, start a Chromium instance with a remote debugging
port and set BIMCP_CDP_URL, for example:
set BIMCP_CDP_URL=http://localhost:9222
pytest -m integration -k cdpLicense
MIT
Available Tools
15 toolsbrowser_act_clickA
Click an element on the page.
REQUIRES: Session must be escalated first via browser_session_escalate.
Args:
session: Name of the browser session
selector: CSS selector for the element to click
reason: Justification for why this click is necessary
Returns:
Observed changes after the click (NOT success/failure)
Inputs: session (required), selector (required), reason (required). Returns: result
browser_act_executeA
Execute JavaScript in the browser context.
REQUIRES: Session must be escalated first via browser_session_escalate.
Args:
session: Name of the browser session
script: JavaScript code to execute
reason: Justification for why this script is necessary
Returns:
Observed changes after execution (NOT success/failure)
Inputs: session (required), script (required), reason (required). Returns: result
browser_act_typeA
Type text into an input element.
REQUIRES: Session must be escalated first via browser_session_escalate.
Args:
session: Name of the browser session
selector: CSS selector for the input element
text: Text to type
reason: Justification for why this input is necessary
clear_first: If True, clear the input before typing
Returns:
Observed changes after typing (NOT success/failure)
Inputs: session (required), selector (required), text (required), reason (required), +1 more. Returns: result
browser_inspect_consoleB
Get captured console log messages from the page.
Args:
session: Name of the browser session
Returns:
JSON array of console entries with level, message, and timestamp
Inputs: session (required). Returns: result
browser_inspect_domA
Get DOM HTML content from the page.
Args:
session: Name of the browser session
selector: Optional CSS selector to get specific element's HTML
Returns:
HTML content (truncated if over 100KB)
Inputs: session (required), selector. Returns: result
browser_inspect_eventsA
Get the event log for a session.
The event log is append-only and records all tool calls made to this session.
Args:
session: Name of the browser session
Returns:
JSON array of all events in chronological order
Inputs: session (required). Returns: result
browser_inspect_networkA
Get captured network requests from the page.
Args:
session: Name of the browser session
Returns:
JSON array of network entries with method, url, status, and timestamp
Inputs: session (required). Returns: result
browser_inspect_screenshotA
Take a screenshot of the current page.
Args:
session: Name of the browser session
full_page: If True, capture the entire scrollable page
Returns:
Base64-encoded PNG screenshot with data URI prefix
Inputs: session (required), full_page. Returns: result
browser_inspect_textA
Get text content from the page (no HTML tags).
Args:
session: Name of the browser session
selector: Optional CSS selector to get specific element's text
Returns:
Text content of the page or element
Inputs: session (required), selector. Returns: result
browser_session_connectA
Connect to an existing browser session over CDP.
Sessions start in observation-only mode. Actions require explicit escalation.
Args:
name: Unique name for the session (e.g., "main", "test-session")
cdp_url: CDP websocket URL (e.g., ws://127.0.0.1:9222/devtools/browser/...)
Returns:
Confirmation message with session name and status
Inputs: name (required), cdp_url (required). Returns: result
browser_session_createA
Create a new browser session for observation.
Sessions start in observation-only mode. Actions require explicit escalation.
Args:
name: Unique name for the session (e.g., "main", "test-session")
headless: If True, run browser without visible window
viewport_width: Browser viewport width in pixels (default: 1280)
viewport_height: Browser viewport height in pixels (default: 720)
Returns:
Confirmation message with session name and status
Inputs: name (required), headless, viewport_width, viewport_height. Returns: result
browser_session_destroyA
Destroy a browser session and clean up resources.
Args:
name: Name of the session to destroy
Returns:
Confirmation message
Inputs: name (required). Returns: result
browser_session_escalateA
Escalate a session to allow action tools (click, type, execute).
WARNING: This enables side effects. Actions will be logged.
Args:
name: Name of the session to escalate
reason: Justification for why actions are needed
Returns:
Warning message and confirmation
Inputs: name (required), reason (required). Returns: result
browser_session_listB
List all browser sessions with their status.
Returns:
List of sessions showing name, status (active/escalated), and current URL
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Every tool has a clearly distinct purpose with no ambiguity. The tools are cleanly divided into 'act' (click, execute, type), 'inspect' (console, dom, events, navigate, network, screenshot, text), and 'session' (connect, create, destroy, escalate, list) categories, each targeting specific browser automation tasks. The descriptions reinforce these distinctions, making misselection unlikely.
Tool names follow a highly consistent verb_noun pattern with a clear prefix structure: 'browser_act_*' for actions, 'browser_inspect_*' for inspection, and 'browser_session_*' for session management. All names use snake_case consistently, and the verb choices (click, execute, type, inspect, connect, create, etc.) are predictable and well-aligned with their functions.
The 15 tools are well-scoped for a browser instrumentation server, covering all essential aspects: session lifecycle management, page inspection, and user interactions. Each tool earns its place without redundancy, and the count is typical for this domain (similar to the GitHub example with 10 tools). No tools feel unnecessary or missing for the core purpose.
The tool surface provides complete coverage for browser automation. It includes session CRUD (create, connect, list, destroy), escalation for actions, comprehensive inspection (dom, text, console, network, events, screenshot, navigation), and core user actions (click, type, execute). There are no obvious gaps; agents can perform full observation and interaction workflows without dead ends.
Related MCP Connectors
Live browser debugging for AI assistants — DOM, console, network via MCP.
A paid remote MCP for AI agent browser DevTools MCP, built to return verdicts, receipts, usage logs,
Real Chrome for coding agents over MCP: browse, replay playbooks, human takeover, HIPAA & BAA.
Safety tools for AI agents: safe page reader, prompt-injection, secrets, PII and MCP server scans