Skip to main content
Glama
Browser Instrumentation MCP Server

Browser Instrumentation MCP Server

by KvFxKaido

Browser Instrumentation MCP Server

Tests

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 chromium

Configuration

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

Available Tools

Session Management

Tool

Description

browser_session_create

Create a new session (observation-only mode)

browser_session_list

List sessions with status and event count

browser_session_destroy

Clean up session

browser_session_escalate

Enable actions (requires reason)

INSPECT Tools (Safe)

Tool

Description

browser_inspect_navigate

Navigate to URL

browser_inspect_screenshot

Capture page screenshot

browser_inspect_dom

Get HTML content

browser_inspect_text

Get text content (no HTML)

browser_inspect_console

Get console log messages

browser_inspect_network

Get network requests

browser_inspect_events

Get session event log

ACT Tools (Require Escalation)

Tool

Description

browser_act_click

Click element (requires reason)

browser_act_type

Type into input (requires reason)

browser_act_execute

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/submitted

Event 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 implementation

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

Testing

# Unit tests only (fast, no browser required)
pytest -m "not integration"

# All tests (includes real browser and CDP integration tests)
pytest

Integration 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 cdp

License

MIT

Available Tools

15 tools
browser_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_navigateA

Navigate to a URL for observation.

Navigation is considered an inspect operation because it sets up
what you want to observe.

Args:
    session: Name of the browser session
    url: URL to navigate to (https:// added if no protocol specified)

Returns:
    The page title and final URL after navigation

Inputs: session (required), url (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

    A4/5.0

    Scored across 15 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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