Package Exports

browser-mcp-native-host
browser-mcp-native-host/host.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (browser-mcp-native-host) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@browser-mcp/native-host

Native Messaging Host for Browser MCP

Bridges AI assistants (Claude Desktop, Cursor, Windsurf) to the Browser MCP Chrome extension via Native Messaging protocol.

🚀 Quick Install

One-Line Installation

npm install -g @browser-mcp/native-host

The installation will:

✅ Install the native messaging host globally
✅ Auto-detect your Browser MCP extension ID
✅ Create native messaging manifest
✅ Configure for your platform (Mac/Linux/Windows)

📦 What's Included

browser-mcp-host - Native messaging host binary
browser-mcp-setup - Configuration CLI tool
Automatic manifest setup - Works on Mac, Linux, Windows

🔧 Usage

Automatic Setup (Recommended)

After installation, the host is automatically configured. Just add to your IDE config:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "browser-mcp": {
      "command": "browser-mcp-host"
    }
  }
}

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "browser-mcp": {
      "command": "browser-mcp-host"
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "browser-mcp": {
      "command": "browser-mcp-host"
    }
  }
}

Manual Configuration

If auto-detection fails, run the setup wizard:

browser-mcp-setup

Or provide extension ID directly:

browser-mcp-setup YOUR_EXTENSION_ID_HERE

Check Configuration Status

browser-mcp-setup --status

Reconfigure

browser-mcp-setup

📍 File Locations

macOS

Host: /usr/local/lib/node_modules/@browser-mcp/native-host/host.js
Manifest: ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.browsermcp.native.json

Linux

Host: /usr/local/lib/node_modules/@browser-mcp/native-host/host.js
Manifest: ~/.config/google-chrome/NativeMessagingHosts/com.browsermcp.native.json

Windows

Host: %APPDATA%\npm\node_modules\@browser-mcp\native-host\host.js
Manifest: %APPDATA%\Google\Chrome\NativeMessagingHosts\com.browsermcp.native.json

🔍 How It Works

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────┐
│   Claude/Cursor │◄───────►│  Native Host     │◄───────►│ Chrome Extension│
│   (AI Assistant)│  stdio  │  (This Package)  │ Native  │   Browser MCP   │
└─────────────────┘         └──────────────────┘ Message └─────────────────┘

AI Assistant sends MCP requests via stdio
Native Host (this package) forwards to Chrome extension
Chrome Extension executes browser debugging commands
Native Host returns results to AI assistant

🛠️ Development

Local Testing

# Clone repository
git clone https://github.com/YOLOVibeCode/browser-mcp.git
cd browser-mcp/native-messaging-host

# Install locally
npm install -g .

# Test
echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | browser-mcp-host

Uninstall

npm uninstall -g @browser-mcp/native-host

This will remove:

The host binary
The manifest file (automatically)

🐛 Troubleshooting

"Extension ID not found"

Load the Browser MCP extension in Chrome first
Run browser-mcp-setup manually
Copy extension ID from chrome://extensions/

"Command not found: browser-mcp-host"

Check npm global bin is in PATH: npm bin -g
Add to PATH if needed: export PATH="$(npm bin -g):$PATH"
Restart terminal

"Native host has exited"

Check manifest exists: browser-mcp-setup --status
Verify extension ID matches
Check logs: Host writes to stderr

Test Connection

# Send test message
echo '{"jsonrpc":"2.0","id":1,"method":"test"}' | browser-mcp-host

📚 API

Command Line

browser-mcp-host              # Run the native messaging host
browser-mcp-setup             # Interactive setup wizard
browser-mcp-setup [id]        # Setup with specific extension ID
browser-mcp-setup --status    # Show current configuration
browser-mcp-setup --version   # Show version
browser-mcp-setup --help      # Show help

Protocol

The host uses the Chrome Native Messaging Protocol:

Input: JSON-RPC 2.0 messages via stdin (4-byte length prefix)
Output: JSON-RPC 2.0 responses via stdout (4-byte length prefix)
Logs: Written to stderr

🤝 Contributing

Contributions welcome!

Fork the repository
Create a feature branch
Make your changes
Test locally with npm install -g .
Submit a pull request

📄 License

MIT License - see LICENSE

🔗 Links

Repository: https://github.com/YOLOVibeCode/browser-mcp
NPM Package: https://www.npmjs.com/package/@browser-mcp/native-host
Issues: https://github.com/YOLOVibeCode/browser-mcp/issues

Made with ❤️ by YOLOVibeCode