Surfbird MCP

Surfbird

Kitesurf, self-hosted. An unofficial Docker distribution of Cloudflare Kitesurf — the experimental browser engine built for AI agents.

Not affiliated with or endorsed by Cloudflare. Kitesurf is Apache-2.0 licensed.

Kitesurf parses HTML, applies CSS, runs page JavaScript and renders screenshots — no Chrome, no browser container — and speaks CDP, so Puppeteer/Playwright connect as usual. Upstream only supports wrangler dev locally or deploying to Cloudflare Workers (paid). Surfbird packages it for any VPS.

Images

Images auto-build daily when upstream cuts a new tag; per-tag pins like terry2010/surfbird:auth-2026.11.8 are also published.

Quick start

# raw — engine only, no auth. Bind loopback/internal only!

docker run -d -p 127.0.0.1:8787:8787 terry2010/surfbird:raw

auth — one command, token + REST actions

docker run -d -p 127.0.0.1:8080:8080 -e SURFBIRD_TOKEN=$(openssl rand -hex 24) terry2010/surfbird:auth

Usage

CDP (Puppeteer / Playwright / chrome-devtools-mcp):

puppeteer.connect({

browserWSEndpoint: "ws:// :8787/devtools/browser", // raw // or auth image: browserWSEndpoint: "ws:// :8080/devtools/browser", headers: { Authorization: "Bearer " }, });

REST (auth image only):

curl -H "Authorization: Bearer $TOKEN" \

-d '{"url":"https://zhuikan.com/repos/terry2010__surfbird","fullPage":true}' \ http:// :8080/screenshot -o page.png

curl -H "Authorization: Bearer $TOKEN" \ -d '{"url":"https://zhuikan.com/repos/terry2010__surfbird"}' \ http:// :8080/markdown | jq -r .markdown

Endpoints: POST /screenshot | /pdf | /content | /source | /markdown | /evaluate | /batch (one action over up to MAX_BATCH_URLS urls, per-item results), GET /health, GET /openapi.json. /content returns the post-JS rendered DOM; /source returns the original response body ("view source"). All other paths transparently proxy to the engine (landing page, /json/*, /rbi/*).

JS/TS client: surfbird on npm — new Surfbird(url,{token}).markdown(u) etc., plus sb.batch(action, urls).

MCP (Model Context Protocol)

Two ways to plug Surfbird into an MCP-capable agent (Claude Code, Cursor, Windsurf, …):

A. `surfbird-mcp` — thin wrapper (recommended). Exposes our REST actions as MCP tools — including surf_markdown and surf_batch, which stock browser MCPs don't have:

{

"mcpServers": { "surfbird": { "command": "npx", "args": ["-y", "surfbird-mcp"], "env": { "SURFBIRD_URL": "http:// :8080", "SURFBIRD_TOKEN": " " } } } }

Tools: surf_markdown surf_content surf_source surf_screenshot surf_pdf surf_evaluate surf_batch surf_health.

B. `chrome-devtools-mcp` — full CDP surface. Points straight at the proxied WebSocket (/devtools/browser passes through with Bearer auth) — more tools, more moving parts. See upstream docs; if your client can't send custom WS headers, run a raw image on a private network instead.

No MCP at all? The REST layer is agent-friendly on its own — skills/surfbird/SKILL.md is a drop-in skill that teaches any agent to drive it with curl.

Examples

examples/ — zero-dep Python client (rss_to_markdown.py builds a feed→markdown digest for LLM daily reports) and bash/curl scripts.

Env

GET /health is unauthenticated and returns 200 only when the engine answers — safe for LB probes. If either process dies, the container exits; use --restart unless-stopped.

Bound to loopback above — reach a remote instance via SSH tunnel (ssh -L 8080:127.0.0.1:8080 user@vps) or a TLS reverse proxy. An exposed engine is a request-making machine on your VPS: token + firewall/TLS are the minimum, never expose raw.

Building

# A) full in-image build (needs ~4GB+ RAM, CI machines):

docker build -f Dockerfile --target raw -t surfbird:raw . docker build -f Dockerfile --target auth -t surfbird:auth .

B) from a locally-built checkout (low-resource hosts):

./scripts/smoke-test.sh # stages a real ctx via tar (symlinks won't work — Docker can't COPY through them)

or manually:

mkdir -p ctx/kitesurf && tar -C /path/to/kitesurf --exclude='*/node_modules' --exclude='*/.git' -cf - . | tar -C ctx/kitesurf -xf - cp -r proxy ctx/proxy && cp entrypoint.sh Dockerfile.prebuilt ctx/ docker build -f ctx/Dockerfile.prebuilt ctx -t surfbird:raw

Pin upstream: --build-arg KITESURF_REF= (Dockerfile A). Engine patches: drop .patch files into patches/, applied after clone.

Limits (from upstream, not Surfbird's fault)

• Experimental engine (Boa JS) — heavy-JS sites may render imperfectly
• No touch/drag gestures, no video decode, no browser-style file downloads
• DevTools frontend excluded from builds (China-network-safe); use CDP
• Auth image adds a token gate — it is not a hardened multi-tenant boundary

License

Apache-2.0. Kitesurf © Cloudflare, Inc. See upstream NOTICE.