Customable - MCPs
Repositories
49
 Projects Packages
17

@customable/browser-mcp (3.0.0)

Published 2025-10-11 08:58:45 +02:00 by jack in customable-mcp/browser-mcp

Installation

@customable:registry=
npm install @customable/browser-mcp@3.0.0
"@customable/browser-mcp": "3.0.0"

About this package

🌍 browser-mcp

Version CI Status License NPM

MCP Server for comprehensive browser automation - featuring multi-browser support (Chromium, Firefox, WebKit), multi-tab management, storage, console debugging, geolocation simulation, network emulation, and full testing capabilities powered by Playwright.

Features

🆕 v3.0.0 - Multi-Browser Support

  • 🌐 Chromium - Fast, feature-rich browser (default)
  • 🦊 Firefox - Mozilla's privacy-focused browser
  • 🧭 WebKit - Apple's browser engine (Safari)
  • 🔄 Automatic browser installation via Playwright
  • 📐 Smart viewport sizing (1920x1080 for GUI mode)

🗂️ Multi-Tab Management

  • 🗂️ create_tab - Create and manage multiple browser tabs
  • 🔄 navigate_tab - Navigate existing tabs to new URLs
  • 📋 list_tabs - List all open tabs with their details
  • ❌ close_tab - Close specific tabs
  • 🎯 All tools support optional tabId parameter to work with persistent tabs

Core Features

  • 🌐 open_page - Open a webpage (one-time or in managed tab)
  • 📄 get_title - Get page title
  • 📸 screenshot - Take screenshot (full page or element)
  • 🔍 query_selector - Query DOM element and get text/attributes
  • ⌨️ fill_form - Fill form fields and submit
  • 🖱️ click_element - Click on element by selector

💾 Storage Management

  • 📦 get_local_storage / set_local_storage / clear_local_storage - LocalStorage control
  • 💿 get_session_storage / set_session_storage / clear_session_storage - SessionStorage control

📝 Console Debugging

  • 🎯 start_console_capture - Start capturing console logs
  • 📋 get_console_logs - Retrieve captured logs with timestamps and source locations
  • 🗑️ clear_console_logs - Clear captured logs

🌍 Device & Network Simulation

  • 📍 set_geolocation - Override device geolocation (latitude, longitude, accuracy)
  • 🌐 emulate_network_conditions - Simulate offline, 3G, latency, throttling

🔧 Runtime Configuration

  • 👁️ set_headless_mode - Toggle headless/GUI mode without restarting
  • 📊 get_headless_mode - Get current headless status

Advanced Features

  • 🍪 Cookie management (get, set)
  • ⚡ Performance metrics (Core Web Vitals, navigation timing, resource performance, memory usage)
  • 📱 Viewport configuration (desktop, mobile, custom)
  • 📋 Extract page content (text, HTML)
  • 📄 PDF extraction
  • 📊 Table and list extraction with pagination

Installation

npm install @customable/browser-mcp

Or install from Forgejo Package Registry:

# Add to your .npmrc
echo "@customable:registry=https://git.customable.host/api/packages/customable-mcp/npm/" >> .npmrc

# Install
npm install @customable/browser-mcp

Configuration

Add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "browser-mcp": {
      "command": "node",
      "args": ["/path/to/node_modules/@customable/browser-mcp/dist/index.js"],
      "env": {
        "HEADLESS": "true",
        "SCREENSHOT_DIR": "./screenshots"
      }
    }
  }
}

Environment Variables

  • HEADLESS - Run in headless mode (default: true, can be changed at runtime with set_headless_mode)
  • SCREENSHOT_DIR - Directory for screenshots (default: ./screenshots)
  • BROWSER_TYPE - Browser engine to use: chromium, firefox, or webkit (default: chromium)

Note:

  • You can change headless mode at runtime using the set_headless_mode tool without restarting!
  • When HEADLESS=false, viewport automatically sizes to 1920x1080 for optimal viewing

Usage

Once configured, the MCP server will be available in Claude Code. You can use tools like:

open_page, screenshot, query_selector, fill_form, click_element, etc.

Examples

Multi-Tab Workflow

// Create a new tab
{
  "tool": "create_tab",
  "arguments": {
    "url": "https://example.com"
  }
}
// Returns: { "tabId": "abc-123...", "url": "https://example.com", "title": "Example Domain" }

// Use the tab for multiple operations
{
  "tool": "screenshot",
  "arguments": {
    "url": "",
    "tabId": "abc-123...",
    "fullPage": true
  }
}

{
  "tool": "get_content",
  "arguments": {
    "url": "",
    "tabId": "abc-123...",
    "type": "text"
  }
}

// Navigate to another page in the same tab
{
  "tool": "navigate_tab",
  "arguments": {
    "tabId": "abc-123...",
    "url": "https://example.org"
  }
}

// List all open tabs
{
  "tool": "list_tabs",
  "arguments": {}
}

// Close the tab when done
{
  "tool": "close_tab",
  "arguments": {
    "tabId": "abc-123..."
  }
}

Take a screenshot (one-time operation)

{
  "tool": "screenshot",
  "arguments": {
    "url": "https://example.com",
    "fullPage": true
  }
}

Query DOM element

{
  "tool": "query_selector",
  "arguments": {
    "url": "https://example.com",
    "selector": "h1",
    "attribute": "textContent"
  }
}

Fill form

{
  "tool": "fill_form",
  "arguments": {
    "url": "https://example.com/form",
    "fields": {
      "#email": "user@example.com",
      "#password": "secret"
    },
    "submit": true
  }
}

Extract tables from a webpage

{
  "tool": "extract_tables",
  "arguments": {
    "url": "https://example.com/data",
    "selector": ".data-table",
    "limit": 5,
    "maxRows": 50
  }
}

Storage Management

// Set localStorage items
{
  "tool": "set_local_storage",
  "arguments": {
    "url": "https://example.com",
    "items": {
      "userId": "12345",
      "theme": "dark"
    }
  }
}

// Get localStorage items
{
  "tool": "get_local_storage",
  "arguments": {
    "url": "https://example.com",
    "keys": ["userId", "theme"]
  }
}

Console Log Capture

// Start capturing logs
{
  "tool": "start_console_capture",
  "arguments": {
    "tabId": "abc-123..."
  }
}

// Get captured logs
{
  "tool": "get_console_logs",
  "arguments": {
    "tabId": "abc-123...",
    "clear": true
  }
}

Geolocation & Network Simulation

// Set geolocation (New York City)
{
  "tool": "set_geolocation",
  "arguments": {
    "url": "https://example.com",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "accuracy": 100
  }
}

// Emulate slow 3G network
{
  "tool": "emulate_network_conditions",
  "arguments": {
    "url": "https://example.com",
    "offline": false,
    "downloadThroughput": 50000,
    "uploadThroughput": 50000,
    "latency": 200
  }
}

Dynamic Headless Mode

// Switch to GUI mode for debugging
{
  "tool": "set_headless_mode",
  "arguments": {
    "headless": false,
    "restart": true
  }
}

// Check current mode
{
  "tool": "get_headless_mode",
  "arguments": {}
}

What's New in v3.0.0

🚀 Major upgrade - Playwright Migration!

  • 🌐 Multi-browser support - Chromium, Firefox, and WebKit
  • ⚡ Modern API - Migrated from Puppeteer to Playwright 1.56.0
  • 🎯 Better selectors - Modern locator API for more reliable element interaction
  • 🔄 Auto-installation - Browsers install automatically via postinstall
  • 📐 Smart viewport - Automatic 1920x1080 viewport in GUI mode
  • 🛠️ Improved reliability - Better network handling and element waiting
  • 🔒 Enhanced type safety - Full TypeScript compatibility with Playwright

Previous Releases

v2.0.0 - Complete refactor with 15 new tools (storage, console, geolocation, network)

See CHANGELOG.md for full details.

License

MIT

Dependencies

Dependencies

ID Version
@modelcontextprotocol/sdk ^1.20.0
playwright ^1.56.0

Development dependencies

ID Version
@types/node ^18.0.0
@vitest/coverage-v8 ^1.0.0
typescript ^5.3.0
vitest ^1.0.0

Keywords

mcp browser playwright automation testing multi-browser
Details
npm
customable-mcp/browser-mcp
2025-10-11 08:58:45 +02:00
4
Customable Team
Project website
MIT
latest
46 KiB
Assets (1)
browser-mcp-3.0.0.tgz 46 KiB
Versions (4) View all
3.0.0 2025-10-11
2.0.0 2025-10-10
1.2.0 2025-10-09
1.0.5 2025-10-07
Issues