aipex-mcp-bridge

MCP server that connects AI agents to the AIPex browser extension. Supports multiple simultaneous clients (Cursor, Claude Code, VS Code Copilot, etc.) via StreamableHTTP.

How it works

Cursor        ──HTTP POST /mcp──┐
Claude Code   ──HTTP POST /mcp──┤── aipex-mcp-server ──WebSocket──▶ AIPex Chrome Extension
VS Code       ──HTTP POST /mcp──┘

The server runs on localhost:9223 and provides:

• /mcp — StreamableHTTP endpoint for MCP clients
• /extension — WebSocket endpoint for the AIPex Chrome extension
• /health — Health check endpoint

Quick start

1. Start the server

npx aipex-mcp-server

The server stays running and handles all AI agent connections.

2. Configure your AI agent

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

{
  "mcpServers": {
    "aipex-browser": {
      "url": "http://localhost:9223/mcp"
    }
  }
}

Claude Code:

claude mcp add --transport http aipex-browser http://localhost:9223/mcp

VS Code Copilot (.vscode/mcp.json):

{
  "servers": {
    "aipex-browser": {
      "url": "http://localhost:9223/mcp"
    }
  }
}

3. Connect AIPex extension

1. Open Chrome → AIPex extension → Options page
2. Set WebSocket URL to ws://localhost:9223/extension
3. Click Connect

Your AI agents can now control the browser through AIPex — all simultaneously.

Options

npx aipex-mcp-server [--port <port>] [--host <host>]

| Option | Default | Description | | --------------- | ----------- | ----------------------------------------------------------- | | --port <port> | 9223 | Server port | | --host <host> | 127.0.0.1 | Bind address (0.0.0.0 to allow remote/Docker connections) | | --help, -h | | Show help message | | --version, -v| | Show version |

Stdio Bridge (backward compatibility)

For MCP clients that only support stdio transport, a thin bridge is included:

{
  "mcpServers": {
    "aipex-browser": {
      "command": "npx",
      "args": ["-y", "aipex-mcp-bridge"]
    }
  }
}

The stdio bridge forwards tool calls to the HTTP server at http://localhost:9223/mcp. The server must be running separately.

AIPex CLI

Command-line tool for controlling the browser directly from the terminal.

Usage

aipex-cli <tool_name> [--param value ...]
aipex-cli --list                              # List all tools
aipex-cli --help <tool_name>                  # Show tool parameters
aipex-cli --json '{"name":"...","arguments":{...}}'  # Raw JSON

Examples

aipex-cli get_all_tabs
aipex-cli create_new_tab --url https://example.com
aipex-cli search_elements --tabId 123 --query "button*"
aipex-cli click --tabId 123 --uid btn-42
aipex-cli capture_screenshot

Environment Variables

| Variable | Default | Description | | --------------------- | --------------------------------- | ----------------------- | | AIPEX_SERVER_URL | http://localhost:9223/mcp | HTTP server URL | | AIPEX_WS_URL | ws://localhost:9223/cli | WebSocket fallback URL | | AIPEX_CONNECT_TIMEOUT| 60000 | Max ms to wait |

Docker Image

docker pull butterman2/aipex-browser:latest
docker run -d --name aipex --shm-size=2g \
  -p 9223:9223 -p 5900:5900 -p 6080:6080 \
  butterman2/aipex-browser:latest

| Port | Service | | ---- | -------------------- | | 9223 | MCP Server (HTTP + WS) | | 5900 | VNC | | 6080 | noVNC (web-based) |

Migration from v2.x

v3.0 replaces the daemon+proxy architecture with a single HTTP server:

| v2.x (daemon) | v3.0 (HTTP server) | | ------------------------------------------ | ----------------------------------------- | | npx aipex-mcp-bridge (stdio per IDE) | npx aipex-mcp-server (one server) | | Each IDE spawns its own bridge process | All IDEs connect to one HTTP endpoint | | Daemon with PID files, idle timeout | Standard HTTP server, no background process| | Extension connects to ws://localhost:9223 | Extension connects to ws://localhost:9223/extension |

Breaking change: The AIPex extension WebSocket URL changed from ws://localhost:9223 to ws://localhost:9223/extension. Update the URL in AIPex extension Options.

Requirements

• Node.js >= 18
• AIPex Chrome extension installed (not needed for Docker image)

License

MIT