AI agents (MCP)
The desktop app includes an MCP server, so AI agents such as Claude Code, Claude Desktop or Cursor can work with your profiles. It is part of the Local API (Pro and higher) and uses the same API key.
Connect
- Turn on the Local API in Settings → Local API and save your API key there (create one in Dashboard → API keys).
- Add the server to your agent. In Claude Code:
claude mcp add --transport http owlxbrowser http://127.0.0.1:50380/mcp --header "Authorization: Bearer lak_your_key"
Other MCP clients that speak Streamable HTTP (Cursor and others): add a server at http://127.0.0.1:50380/mcp with the header Authorization: Bearer <your API key>. Use your own port if you changed it.
Apps that only start local commands (Claude Desktop)
Use the small bridge mcp-stdio-bridge.mjs from the examples folder (it needs Node.js 18 or newer and nothing else). It passes the app's messages to the MCP server above:
{
"mcpServers": {
"owlxbrowser": {
"command": "node",
"args": ["C:/path/to/mcp-stdio-bridge.mjs"],
"env": { "OWLX_API_KEY": "lak_your_key", "OWLX_API_PORT": "50380" }
}
}
}
The server only listens on your computer (127.0.0.1) and refuses requests from web pages. On a server, start the app in headless mode and connect the same way.
Tools
| Tool | What it does |
|---|---|
list_profiles | Profiles with id, number, name, state, OS, proxy and tags (optional search) |
create_profile | New profile with a fresh, consistent fingerprint; optional OS, proxy string, group and tags |
start_profile / stop_profile | Opens or closes a profile's browser; start returns its DevTools endpoint |
list_running | Profiles open on this computer, with their endpoints |
open_url | Opens an address in a running profile and waits for it to load |
page_text | The current page's address, title and visible text |
screenshot | A picture of the current page |
move_profile | Puts a profile into a group (or out of it) |
clear_cache | Deletes a stopped profile's cache (logins stay) |
get_cookies / set_cookies | Reads or adds a profile's cookies (needs the role permission "Export and import cookies") |
list_proxies / check_proxy | Saved proxies (never their passwords) and a live check from your computer |
list_groups | Profile groups |
list_flows / run_flow / get_run | Your RPA flows: list them, run one on profiles, follow its progress |
In a team, the agent can do what your role allows, nothing more.
Profiles are real accounts: tell the agent what it may do, and keep an eye on it the first times.
A skill for coding agents
Coding agents (Claude Code, Codex, Cursor and others) write better scripts for OwlXBrowser when they know how the Local API works. Save the text below as .claude/skills/owlxbrowser/SKILL.md in your project (Claude Code), or paste it into your agent's instructions file (AGENTS.md, Cursor rules).
---
name: owlxbrowser
description: Drive OwlXBrowser antidetect profiles from scripts through its Local API (start/stop profiles, connect Playwright/Puppeteer/Selenium, manage profiles, proxies, tags, RPA flows). Use when writing automation that opens OwlXBrowser profiles.
---
# OwlXBrowser Local API
- Base URL: `http://127.0.0.1:50380` (the port is set in the app under API & Developers). Every request sends `Authorization: Bearer <API key>`; keys start with `lak_`. Never hard-code the key: read it from an environment variable (e.g. `OWLX_API_KEY`).
- The desktop app must be running and signed in (or started headless on a server). The API only answers on 127.0.0.1.
- Rate limits depend on the plan: on HTTP 429, wait for `Retry-After` seconds.
## Profiles
- `GET /v1/profiles?search=&group=&tag=` → `{ data: [...] }` (id, name, notes, engine, group_id, proxy_id, tags, status)
- `POST /v1/profiles` `{ name, template_id? ("chromium-windows", "chromium-macos", "cf-windows"…), group_id?, proxy_id?, tags?, notes? }`
- `PATCH /v1/profiles/{id}` · `DELETE /v1/profiles/{id}` · `POST /v1/profiles/{id}/move` `{ group_id }`
- `POST /v1/profiles/{id}/new-fingerprint` (closed profiles) · `GET /v1/profiles/{id}/user-agent`
- `GET|POST /v1/profiles/{id}/cookies` · `POST /v1/profiles/{id}/clear-cache`
## Open and automate
- `POST /v1/profiles/{id}/start` `{ headless?: boolean }` → `{ protocol, endpoint, debug_port, debugger_address }`
- `protocol: "cdp"` (Chrome engines): Playwright `chromium.connectOverCDP(endpoint)`, Puppeteer `puppeteer.connect({ browserWSEndpoint: endpoint })`, Selenium `debuggerAddress = debugger_address`.
- `protocol: "bidi"` (Firefox profiles): Puppeteer `puppeteer.connect({ browserWSEndpoint: endpoint, protocol: "webDriverBiDi" })`.
- Use the existing context and pages; don't launch a new browser and don't change the user agent, viewport or timezone yourself (the profile's fingerprint already sets them consistently).
- `POST /v1/profiles/{id}/stop` · `POST /v1/profiles/stop-all` · `GET /v1/profiles/running` · `GET /v1/profiles/{id}/status`
## Proxies, groups, tags
- `GET|POST /v1/proxies`, `PATCH|DELETE /v1/proxies/{id}`, `POST /v1/proxies/{id}/check` — types: `http`, `https`, `socks5`, `ssh`. Passwords are never returned.
- `GET|POST /v1/groups`, `PATCH /v1/groups/{id}` · `GET|POST /v1/tags`, `PATCH|DELETE /v1/tags/{id}`
## RPA flows
- `GET /v1/flows` · `POST /v1/flows/{id}/run` `{ profile_ids: [...], options?: { concurrency, closeAfter, repeat, headless } }` → task; follow it with `GET /v1/tasks/{taskId}`.
## Scripts written for AdsPower or Dolphin{anty}
They work with the port changed and the API key added: AdsPower `/api/v1/browser/start|stop|active`, `/api/v1/user/*`, `/api/v1/group/*` and the v2 `/api/v2/browser-profile/*`, `/api/v2/browser-tags/*`, `/api/v2/proxy-list/*` routes; Dolphin `/v1.0/browser_profiles/{id}/start|stop`.
## Good practice
- Profiles are real accounts: act like a person (waits, scrolling), one script per profile at a time, and stop the profile when done.
- Handle errors: 401 wrong key, 403 plan or role, 404 unknown profile, 409 profile open elsewhere or busy, 422 invalid input.