Multilogin Browser MCP

A FastAPI service that drives Multilogin X anti-detect browser profiles over CDP and exposes them to AI agents through a streamable HTTP MCP server.

Features

• Profile management — list, search, create, and remove Multilogin profiles (batch create is supported without an artificial cap).
• Browser sessions — start a profile, connect Playwright over CDP, and manage the session lifecycle.
• Browser action catalog — navigate, click, type, evaluate JS, screenshots, tabs, cookies, scroll, hover, and more.
• Dual interface — REST API for integrations and MCP for agent frameworks.
• Session watchdog — 15-minute max TTL and idle timeout cleanup.
• Railway-ready — PORT and .env driven.

Requirements

• Python 3.12+
• Multilogin desktop app / agent running locally (exposes the launcher at https://launcher.mlx.yt:45001, resolving to 127.0.0.1)
• A Multilogin automation token, or username + password

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

No playwright install is required — we connect over CDP to the browser Multilogin launches.

Configuration

Copy the example and fill in the values:

cp .env.example .env

# Option A: automation token (recommended for servers)
MULTILOGIN_AUTOMATION_TOKEN=your_token

# Option B: username + password
# MULTILOGIN_USERNAME=you@example.com
# MULTILOGIN_PASSWORD=your_password

# Optional overrides
# MULTILOGIN_API_URL=https://api.multilogin.com
# MULTILOGIN_LAUNCHER_URL=https://launcher.mlx.yt:45001
# PORT=8000
# SESSION_MAX_TTL_SECONDS=900
# SESSION_IDLE_TIMEOUT_SECONDS=300
# MULTILOGIN_DEBUG_HTTP=1   # log every outgoing Multilogin request (auth masked)

When MULTILOGIN_AUTOMATION_TOKEN is set it is always used and MULTILOGIN_USERNAME / MULTILOGIN_PASSWORD are ignored — the two auth modes are never combined in one request. Set only one of them to avoid confusion.

Run

python main.py
# or
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

• REST docs: http://localhost:8000/docs
• MCP endpoint: http://localhost:8000/mcp (both /mcp and /mcp/ are served directly, no redirect)

REST API

Method	Path	Purpose
GET	/api/v1/profiles/	List/search profiles
POST	/api/v1/profiles/search	Search profiles
POST	/api/v1/profiles/	Create a profile
POST	/api/v1/profiles/bulk	Create many profiles
POST	/api/v1/profiles/remove	Remove profiles
GET	/api/v1/profiles/folders	List workspace folders
POST	/api/v1/profiles/folders	Create a workspace folder
GET	/api/v1/profiles/statuses	Running profiles (launcher)
POST	/api/v1/sessions/	Launch a session (start profile + connect)
GET	/api/v1/sessions/	List active sessions
GET	/api/v1/sessions/{id}	Session status/expiry
DELETE	/api/v1/sessions/{id}	Close session + stop profile
GET	/api/v1/browser/actions	List available browser actions
POST	/api/v1/browser/sessions/{id}/action	Run an action on a session
GET	/api/v1/diagnostics	Effective auth mode, egress IP, and live probes of the Multilogin API

Example flow

# 1. list profiles
curl http://localhost:8000/api/v1/profiles/

# 1b. create a profile (folder_id defaults to the first workspace folder,
#     browser_type/os_type default to mimic/windows)
curl -X POST http://localhost:8000/api/v1/profiles/ \
  -H 'content-type: application/json' \
  -d '{"name":"agent-1"}'

# 2. launch a session
curl -X POST http://localhost:8000/api/v1/sessions/ \
  -H 'content-type: application/json' \
  -d '{"profile_id":"<pid>","folder_id":"<fid>"}'

# 3. drive it
curl -X POST http://localhost:8000/api/v1/browser/sessions/<sid>/action \
  -H 'content-type: application/json' \
  -d '{"action":"navigate","params":{"url":"https://example.com"}}'

# 4. close (auto-closes after 15 min anyway)
curl -X DELETE http://localhost:8000/api/v1/sessions/<sid>

MCP Tools

Point any streamable-HTTP MCP client at http://localhost:8000/mcp/.

Discovery

• list_profiles
• search_profiles
• list_folders
• create_folder

Profile management

• create_profile — create one profile
• create_profiles — create any number of profiles in one call (no artificial limit)
• remove_profiles

Sessions

• launch_session
• session_status
• list_sessions
• close_session

Browser

• browser_action — run any action by name
• list_browser_actions — see the full catalog

The full action catalog includes: navigate, click, type_text, press_key, get_text, get_html, get_url, screenshot, wait_for, evaluate_js, list_tabs, switch_tab, new_tab, close_tab, go_back, go_forward, reload, scroll, hover, select_option, set_checked, upload_file, cookies.

Example client config

{
  "mcpServers": {
    "multilogin-browser": {
      "url": "http://localhost:8000/mcp/"
    }
  }
}

Troubleshooting

405 Method Not Allowed when creating a profile — you are calling an endpoint that does not accept that method. Profile creation is POST /api/v1/profiles/ (REST) or the create_profile / create_profiles MCP tools. Note that the MCP endpoint itself only speaks POST (plus GET/DELETE for SSE and session teardown) on /mcp.

503 with "Cannot reach Multilogin" — the local launcher (https://launcher.mlx.yt:45001) or api.multilogin.com is unreachable. Start the Multilogin X desktop app / agent, or fix MULTILOGIN_LAUNCHER_URL / MULTILOGIN_API_URL. Only launcher calls (/statuses, session launch/stop) need the desktop app; profile CRUD goes to the cloud API and works headlessly with a token.

502 with "answered 501 with an HTML page" — the POST never reached the Multilogin API. api.multilogin.com sits behind an edge that answers POSTs from blocked networks (cloud/datacenter IPs, e.g. Railway) with a canned 501 Unsupported method ('POST') HTML page, while GETs from the same host and token reach the real API (they return proper JSON such as 401 Wrong JWT token). It is therefore not a credential or request-format problem. Confirm with GET /api/v1/diagnostics, which probes both methods and reports the egress IP. Fixes: run this service from a network Multilogin accepts (the machine running Multilogin X, which the launcher/CDP part needs anyway), or ask Multilogin support to allowlist your egress IP.

MCP requests rejected with a security error — set MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS to your public host when running behind a proxy. When both are empty, DNS-rebinding protection is disabled and all hosts are accepted.

Deployment

Colocated with Multilogin X (recommended)

Run the server on the machine that has the Multilogin X desktop app / agent installed, and expose it with a tunnel. This is the only layout where both halves work:

• The launcher binds to 127.0.0.1 (launcher.mlx.yt resolves to 127.0.0.1), so GET /api/v2/profile/f/{folder}/p/{profile}/start returns a port whose CDP endpoint is ws://127.0.0.1:<port>/devtools/.... There is no cloud CDP URL — only a process on the same machine can attach.
• api.multilogin.com blocks profile/workspace POSTs from cloud/datacenter networks (see Troubleshooting), so cloud hosts can't do profile CRUD either.

cp .env.example .env   # set MULTILOGIN_AUTOMATION_TOKEN
./scripts/serve-with-tunnel.sh

That starts the server on 127.0.0.1:8000 and a Cloudflare quick tunnel, printing a public https://<random>.trycloudflare.com URL. For a URL that survives restarts, create a named tunnel once and pass it in:

cloudflared tunnel login
cloudflared tunnel create mlx-mcp
cloudflared tunnel route dns mlx-mcp mlx-mcp.yourdomain.com
TUNNEL_NAME=mlx-mcp ./scripts/serve-with-tunnel.sh

Point the agent at https://<your-tunnel-host>/mcp. With a stable hostname, set MCP_ALLOWED_HOSTS=<your-tunnel-host> in .env so DNS-rebinding protection is on and scoped to it.

Railway

1. Push the repo.
2. Set the environment variables from .env in Railway.
3. Set the start command to python main.py (or uvicorn app.main:app --host 0.0.0.0 --port $PORT).

Note on the launcher

The Multilogin desktop launcher currently resolves to 127.0.0.1. For remote hosts (e.g. Railway), the launcher must either run on the same host or be reachable through a tunnel / VPN.

License

MIT