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

INSPECT Tools (Safe)

ACT Tools (Require Escalation)

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