Click on "Install 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 Servernavigate 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
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.