VPS Browser MCP

Control your local Chrome browser from a remote VPS. Cross-platform Chrome extension with WebSocket bridge for secure remote browser automation. MCP (Model Context Protocol) compatible.

🎯 What is this?

VPS Browser MCP is a system that allows you to remotely control and inspect a Chrome browser running on your personal laptop from a Virtual Private Server (VPS). It's perfect for:

• Remote debugging web applications

• Automated testing from different network locations

• Secure browser automation without exposing your browser publicly

• Web scraping with full browser capabilities

• Remote technical support and troubleshooting

• AI/LLM integration via MCP (Model Context Protocol)

Related MCP server: Chrome DevTools MCP

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   VPS Agent     │◄──►│  Local Bridge   │◄──►│ Chrome Extension│
│   (Node.js)     │    │  (Node.js)      │    │  (Manifest V3)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                      │                      │
         │                      │                      │
         ▼                      ▼                      ▼
   WebSocket              WebSocket              Chrome APIs
   (Tailscale/SSH)        (localhost)            (tabs, scripting)

Components

1. Chrome Extension (Manifest V3)

   • Runs in your local Chrome browser

   • Executes browser actions via Chrome APIs

   • Maintains WebSocket connection to local bridge

   • Handles tab management, DOM inspection, script execution

2. Local Bridge (Node.js)

   • Lightweight service running on your laptop

   • Bridges WebSocket connections between VPS and Chrome extension

   • Routes commands and responses

   • Keeps connections alive with ping/pong

3. VPS Agent (Node.js)

   • Module running on your remote server

   • Sends structured JSON commands

   • Receives execution results and logs

   • Simple API for browser automation

🚀 Quick Start

Prerequisites

• Node.js (v16 or higher) - Download

• Chrome browser - Download

• Remote access (optional): SSH or Tailscale

Installation

# Clone the repository
git clone https://github.com/Parithosh-Varma/VPS-browser-MCP.git
cd VPS-browser-MCP

# Run setup (installs dependencies)
npm run setup

# Install Chrome extension
npm run install-extension

# Start the bridge
npm start

3-Step Usage

1. Setup: npm run setup (one-time installation)

2. Install Extension: npm run install-extension (opens Chrome extensions page)

3. Start: npm start (launches WebSocket bridge)

📖 Usage Examples

Basic Commands

const BrowserController = require('./vps_agent/vps_client_example');

// Create controller instance
const browser = new BrowserController();
await browser.connect();

// Get current page URL and title
const pageInfo = await browser.getUrl();
console.log(pageInfo);
// { url: 'https://example.com', title: 'Example Domain' }

// Click an element
await browser.click('#submit-button');

// Type in a search box
await browser.type('#search-input', 'hello world');

// Execute custom JavaScript
const result = await browser.executeJs('document.title.length');
console.log(result); // 13

// Take a screenshot
const screenshot = await browser.screenshot();
// Returns base64 encoded PNG image

// Get DOM content
const dom = await browser.getDom();
console.log(dom.html); // Full page HTML
console.log(dom.elements); // Array of elements

Advanced Usage

// Execute complex JavaScript
const complexResult = await browser.executeJs(`
  // Get all links on the page
  const links = Array.from(document.querySelectorAll('a'));
  links.map(link => ({
    text: link.textContent,
    href: link.href
  }));
`);

// Get specific element's DOM
const elementDom = await browser.getDom('#main-content');

// Type with validation
await browser.type('input[name="email"]', 'user@example.com');

// Click and wait for navigation
await browser.click('a[href="/dashboard"]');

🛠️ Available Commands

🔒 Security Features

• No public exposure: Extension only connects to localhost

• Encrypted tunneling: Use SSH or Tailscale for remote access

• Local execution: Scripts run in your browser's security context

• Permission-based: Extension only accesses what you allow

• No data storage: Everything runs in memory, no logs saved

🌐 Remote Access Options

Option 1: SSH Tunnel (Recommended)

On your VPS:

# Create SSH tunnel to forward port 9877
ssh -R 9877:127.0.0.1:9877 user@your-laptop-ip -N

# Keep tunnel running in background
ssh -R 9877:127.0.0.1:9877 user@your-laptop-ip -N -f

On your VPS (in another terminal):

# Connect to the bridge
node vps_agent/vps_client_example.js

Option 2: Tailscale (Zero-Config)

1. Install Tailscale on both machines:

   # macOS/Linux
   curl -fsSL https://tailscale.com/install.sh | sh
   
   # Windows: Download from https://tailscale.com/download/

2. Login on both machines:

   tailscale up

3. Use the Tailnet IP in your connection:

   const browser = new BrowserController('ws://100.x.x.x:9877');

📁 Project Structure

VPS-browser-MCP/
├── extension/                    # Chrome Extension
│   ├── manifest.json            # Extension configuration
│   ├── background.js            # Service worker (WebSocket handler)
│   ├── content.js               # Content script (page injection)
│   └── inject.js                # Injected script (DOM access)
│
├── local_bridge/                 # Bridge Server
│   ├── local_bridge.js          # WebSocket bridge server
│   └── package.json             # Dependencies
│
├── vps_agent/                    # VPS Client
│   ├── vps_client_example.js    # Example client with BrowserController class
│   └── package.json             # Dependencies
│
├── setup.js                     # Cross-platform setup script
├── start.js                     # Cross-platform service starter
├── install-extension.js         # Chrome extension installer
├── package.json                 # Root package configuration
├── README.md                    # This file
└── LICENSE                      # MIT License

🎨 Features

Chrome Extension Capabilities

• Tab Management: Query, create, update, and remove tabs

• DOM Inspection: Query elements, get HTML, inspect attributes

• Script Execution: Run arbitrary JavaScript in page context

• Event Handling: Click elements, type text, trigger events

• Screenshot Capture: Take PNG screenshots of visible tabs

• Console Access: Capture console logs and errors

Bridge Features

• Bidirectional Communication: Commands flow VPS → Extension, results flow back

• Connection Management: Automatic reconnection and keep-alive

• Multiple Clients: Support for multiple VPS agents simultaneously

• Message Routing: Proper command/response correlation with UUIDs

• Error Handling: Graceful error recovery and reporting

VPS Agent Features

• Simple API: Easy-to-use methods for common operations

• Async/Await: Modern JavaScript async patterns

• Type Safety: Clear result types and error handling

• Extensible: Easy to add custom commands

• Logging: Built-in logging for debugging

🔧 Configuration

Environment Variables

Create a .env file (created automatically by setup):

# Extension WebSocket port (Chrome connects here)
EXTENSION_WS_PORT=9876

# VPS Agent WebSocket port (Remote agent connects here)
VPS_WS_PORT=9877

# VPS Agent connection URL
VPS_WS_URL=ws://127.0.0.1:9877

Chrome Extension Permissions

The extension requires these permissions:

• tabs: Access tab information

• activeTab: Access current active tab

• scripting: Execute scripts in tabs

• webNavigation: Monitor page navigation

🐛 Troubleshooting

Extension not connecting?

1. Ensure the bridge is running: npm start

2. Check Chrome console for errors: Right-click extension → Inspect

3. Verify WebSocket port is available: netstat -an | grep 9876

VPS can't connect?

1. Verify SSH tunnel is active: ssh -R 9877:127.0.0.1:9877 user@laptop-ip -N

2. Check firewall allows port 9877

3. Test connection: telnet localhost 9877

Commands not working?

1. Ensure extension has required permissions (check chrome://extensions/)

2. Check Chrome DevTools console for errors

3. Verify the page you're trying to control is fully loaded

Bridge crashes?

1. Check Node.js version: node --version (need v16+)

2. Reinstall dependencies: npm run setup

3. Check for port conflicts: lsof -i :9876 or netstat -an | grep 9876

📊 JSON Command Schema

Request Format

{
  "id": "uuid-v4-string",
  "action": "get_url | get_dom | click | type | execute_js | screenshot",
  "target": "current_tab | tab_id | {selector: string}",
  "payload": {
    "text": "string",
    "js": "string",
    "selector": "css-selector",
    "wait": 0
  },
  "timestamp": "ISO-8601-UTC-string"
}

Response Format

{
  "id": "matching-request-id",
  "status": "ok | error",
  "result": {},
  "error": {
    "code": "ERR_TIMEOUT | ERR_NOT_FOUND | ERR_PERMISSION",
    "message": "human-readable error"
  },
  "timestamp": "ISO-8601-UTC-string"
}

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/AmazingFeature)

3. Commit your changes (git commit -m 'Add some AmazingFeature')

4. Push to the branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• WebSocket - Browser API for real-time communication

• Chrome Extensions - Chrome extension documentation

• Node.js - JavaScript runtime for bridge and VPS agent

• ws - WebSocket library for Node.js

📞 Support

If you have any questions or issues, please:

1. Check the Troubleshooting section

2. Open an issue on GitHub Issues

3. Contact: [Your Email or Discord]

Made with ❤️ for the developer community