🌐 Agent Browser API

A universal, fully working headless-browser for AI agents. Give any agent — Zapier Agents, Custom GPTs, Claude, Cursor, LangChain, CrewAI, n8n, Make, or your own code — a real Chromium browser: JavaScript rendering, web search, clicking, typing, form filling, dropdowns, screenshots, table & data extraction, and PDF generation.

🇮🇳 Hindi TL;DR: Yeh ek real browser hai jo koi bhi AI agent use kar sakta hai — 3 tarike: simple REST API, OpenAPI import (Custom GPT), ya native MCP (Claude/Cursor/ChatGPT). Deploy karo, API key set karo, ho gaya. ✅ 26/26 tests passing.

🔌 Works with ANY agent — three ways to connect

Mode	For	How
REST API	Zapier Agents, n8n, Make, LangChain, CrewAI, any code	POST /v1/browse {"url": "..."} with X-API-Key header. Auto-discover via GET /v1/tools (OpenAI function format).
OpenAPI	OpenAI Custom GPTs (Actions), API tooling	Import /openapi.yaml — every endpoint documented.
MCP 🆕	Claude Desktop/Code, Cursor, Windsurf, ChatGPT, VS Code, n8n MCP	Point your MCP client at https://YOUR-URL/mcp (Streamable HTTP) — 22 browser tools appear natively.

Full copy-paste guides per platform: INTEGRATIONS.md · Zapier specifics: ZAPIER_SETUP.md

✨ Features

Capability	Endpoint	What it does
📖 Browse	POST /v1/browse	Renders any page (JS included) → clean Markdown + title + links + metadata. LLM-ready.
🔍 Search	POST /v1/search	Web search via Brave/Bing/DDG with auto-fallback. No search API key needed.
📸 Screenshot	POST /v1/screenshot	PNG of page, full page, or a single element; custom viewport; binary or base64.
🧲 Extract	POST /v1/extract	Structured data via CSS selectors → JSON.
📊 Tables	POST /v1/tables	All data tables on a page → JSON (headers + rows), layout/hidden tables skipped.
🖱️ Elements	POST /v1/elements	Visible links/buttons/inputs with ready-to-use CSS selectors — agents can see what's clickable.
📄 PDF	POST /v1/pdf	Render any page to PDF (portrait/landscape).
🧭 Sessions	POST /v1/sessions + actions	Stateful multi-step flows: goto, click, type, fill, press, select, scroll, navigate (back/forward/reload), wait, evaluate, content, elements, screenshot.
🤝 MCP	POST /mcp	All of the above as native MCP tools (screenshots returned as real images).

Plus: API-key auth, CORS, rate limiting, SSRF guard, session auto-expiry + LRU eviction, stealth basics, SPA settle waits, output truncation for LLM context safety, helpful error hints, /llms.txt, and a full OpenAPI spec.

🚀 Quick start

Deploy free (Render) — recommended

1. Fork/push this repo to GitHub.
2. Go to render.com → New → Blueprint → pick this repo (render.yaml auto-detected).
3. Copy the generated API_KEY from the service's Environment tab.
4. Live at https://your-service.onrender.com 🎉

Also works on Railway, Fly.io, or any Docker host.

Docker

docker build -t agent-browser .
docker run -p 8080:8080 -e API_KEY=your-secret-key agent-browser

Run locally

npm install            # installs deps + Chromium
API_KEY=your-secret-key npm start
# → agent-browser v2.0.0 listening on :8080

🧪 Try it

BASE=http://localhost:8080; KEY=your-secret-key

# Read a JS-heavy page as markdown
curl -X POST $BASE/v1/browse -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://news.ycombinator.com"}'

# Search the web
curl -X POST $BASE/v1/search -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"query":"best CRM for startups","limit":5}'

# Extract every table on a page as JSON
curl -X POST $BASE/v1/tables -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://www.scrapethissite.com/pages/forms/"}'

# Multi-step: search Wikipedia interactively
SID=$(curl -s -X POST $BASE/v1/sessions -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://en.wikipedia.org"}' | jq -r .sessionId)
curl -X POST $BASE/v1/sessions/$SID/fill -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"fields":{"input[name=search]":"Artificial intelligence"}}'
curl -X POST $BASE/v1/sessions/$SID/press -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"key":"Enter"}'
curl $BASE/v1/sessions/$SID/content -H "X-API-Key: $KEY"
curl -X DELETE $BASE/v1/sessions/$SID -H "X-API-Key: $KEY"

Run the full smoke-test suite: npm test — 26 checks covering every endpoint and a real MCP client round-trip.

⚙️ Configuration (env vars)

Variable	Default	Description
API_KEY	(empty = auth off, dev only!)	Required key for all non-public endpoints.
PORT	8080	HTTP port.
MAX_SESSIONS	10	Max concurrent stateful sessions (LRU eviction).
SESSION_TTL_MS	600000	Idle session expiry (10 min).
NAV_TIMEOUT_MS	30000	Navigation timeout.
RATE_LIMIT_PER_MIN	120	Requests/min per API key or IP (0 = off).
CORS_ORIGIN	*	Allowed CORS origin.
ALLOW_PRIVATE_URLS	false	Allow browsing private/internal addresses (SSRF guard off).

🔒 Security notes

• Always set API_KEY in production (Render blueprint generates one automatically).
• Only http/https URLs are allowed; localhost/private/metadata addresses are blocked by default.
• Run behind HTTPS (Render/Railway give you TLS for free).
• evaluate runs arbitrary JS inside the sandboxed page — keep your API key secret.
• Public (no key) endpoints are read-only info: /, /health, /openapi.yaml, /llms.txt, /v1/tools.

📁 Project structure

src/server.js         # Express API: auth, CORS, rate limit, routes
src/actions.js        # Shared high-level actions (used by REST + MCP)
src/browser.js        # Chromium lifecycle, sessions, TTL/LRU, SSRF guard
src/extract.js        # HTML → markdown, CSS extraction, tables, elements
src/search.js         # Multi-engine web search with fallback
src/mcp.js            # MCP server (Streamable HTTP, 22 tools)
src/tools-manifest.js # GET /v1/tools (OpenAI function format)
openapi.yaml          # Full API specification
test/run-tests.sh     # 26-check smoke-test suite (incl. MCP round-trip)
Dockerfile            # Production image (Playwright base, version-pinned)
render.yaml           # One-click Render deploy

License

MIT