# Browser Instrumentation MCP Server
[](https://github.com/KvFxKaido/browser-instrumentation-mcp/actions/workflows/tests.yml)
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
```bash
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`
```json
{
"mcpServers": {
"browser": {
"command": "python",
"args": ["-m", "browser_instrumentation_mcp.server"]
}
}
}
```
### Claude Code
```bash
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:
```json
[
{"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
```bash
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
```bash
# 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:
```bash
set BIMCP_CDP_URL=http://localhost:9222
pytest -m integration -k cdp
```
## License
MIT
