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