Skip to content

README.md

Latest commit

 

History

History
171 lines (123 loc) · 4.84 KB

README.md

File metadata and controls

171 lines (123 loc) · 4.84 KB

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