# 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

```bash
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:

```bash
cp .env.example .env
```

```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
```

## Run

```bash
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/` (POST; `GET /mcp` redirects here)

## REST API

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/profiles/` | List/search profiles |
| POST | `/api/v1/profiles/search` | Search profiles |
| 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 |

### Example flow

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

# 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`

### 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

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

## Deployment

### 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