Home / Getting started / Agents

Agent quickstart: MCP, REST, Docker

Three doors into the same browser. Pick the one that matches what you are building; each is a copy-paste block and a restart. Ports: REST on 3000, WebDriver on 9515, CDP on 9222, all configurable in Settings. WebDriver and CDP are off until you turn them on there.

0. Install (one minute)

Needs Node 18+. Downloads the portable build for your OS on first run, caches it under ~/.lumabrowser/, launches it. Prefer a normal install? Native installers. On first launch pick Guided Setup if you want to paste an API key up front; Automatic if you want a local model. Either way the REST API is on as soon as the window opens.

1. MCP: Claude Desktop, Cursor, OpenClaw, anything MCP

The quickest way is Settings > Connect your agent, which writes the entry into Claude Code, Codex, OpenCode and Cline for you. For any other host, Export MCP Configuration in Settings saves luma-mcp-config.json; merge it under mcpServers in your host's config and restart the host. By hand it looks like this:

{
  "mcpServers": {
    "luma-browser": {
      "command": "node",
      "args": ["<install dir>/resources/app.asar.unpacked/mcp-server.js"],
      "env": { "LUMA_API_PORT": "3000" }
    }
  }
}

The server runs on Node.js, so Node must be installed, and it starts LumaBrowser if it is not already running. Your agent now has navigate, click, type, fill_form, observe_page, screenshot, get_source, and the rest, each backed by a real Chromium tab. Full list and the element-reference conventions: MCP server reference.

2. REST: open a page, click with a fallback, read it

# Open a tab
curl -X POST http://localhost:3000/api/browser/tabs \
  -H "Content-Type: application/json" \
  -d '{"url": "https://news.ycombinator.com"}'

# Click. If the selector is stale, the LLM resolves the description instead.
curl -X POST http://localhost:3000/api/browser/tabs/0/click \
  -H "Content-Type: application/json" \
  -d '{"selector": ".titleline > a", "llmFallback": "Click the first story link"}'

# Read the page as clean text
curl http://localhost:3000/api/browser/tabs/0/source?type=text

Every selector call accepts llmFallback; the fallback is logged per call so you can audit it. Forms, waits, scrolling, screenshots, network capture, and webhooks are all under the same base. REST reference.

Selenium, Playwright, Puppeteer

Turn on the WebDriver and CDP servers in Settings (both are off by default), then your existing scripts attach unchanged: Selenium to the WebDriver server on 9515; Playwright with chromium.connectOverCDP('http://127.0.0.1:9222'); Puppeteer with puppeteer.connect({ browserURL: 'http://127.0.0.1:9222' }). Clients only see the tabs automation created, never yours. Details per driver.

3. Docker: headless, with a web desktop

git clone https://github.com/amurgola/LumaBrowser.git
cd LumaBrowser
LUMA_VNC_PASSWORD=change-me docker compose up -d

No prebuilt image is published; compose builds it from the repo. REST API and MCP proxy on 3000, a noVNC desktop on 6080 so you can watch the agent work. In Docker the API accepts any address and needs no key by default, so do not expose port 3000 to a network you do not trust. Point it at a model on the host with LUMA_LLM_PROVIDER and friends; the Docker guide has the compose file and every variable.

What people build first

• An agent that browses for real from Claude Desktop or Cursor, with the MCP block above. Ten minutes.
• A change monitor that fires a webhook when an element on a page changes. No usage caps.
• An n8n / Zapier / Make step that drives a real browser without per-minute cloud pricing. Recipe.
• Sub-agents with their own tools and knowledge base, orchestrated from one chat. Sub-agents.
• Your own chat tools, built in a sandbox by the assistant and published to itself. Code Mode and Tool Forge.