terry2010 /surfbird
Kitesurf, self-hosted — unofficial Docker distribution of Cloudflare's headless browser engine for AI agents. CDP + token auth + REST actions (screenshot/pdf/markdown) + MCP tools, all in one container.
★ 1⑂ 1👁 1⑃ 0● 0▤ 1
+0
日增长
1
stars
1
forks
1
watchers
0
prs
0
issues
1
releases
README
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
| Tag | Contents | Use |
|---|---|---|
| terry2010/surfbird:raw | engine only, :8787 | local / behind your own gateway |
| terry2010/surfbird:auth | engine + token auth proxy + optional TLS, :8080 | one-command, exposed |
| terry2010/surfbird:latest | = :auth | convenience default |
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
bash
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):
js
puppeteer.connect({
browserWSEndpoint: "ws://:8787/devtools/browser", // raw
// or auth image:
browserWSEndpoint: "ws://:8080/devtools/browser",
headers: { Authorization: "Bearer " },
});
REST (auth image only):
bash
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:
json
{
"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 tLatest release
kitesurf 2026.11.9 kitesurf-2026.11.9 2026-11-14Docker images built from upstream kitesurf 2026.11.9. | image | pull | |---|---| | auth — REST actions + token auth + optional TLS | docker pull terry2010/surfbird:auth-2026.11.9 | | raw — engine + CDP only | docker pull terry2010/surfbird:raw-2026.11.9 | Floating tags raw / auth / latest point at this build. Unofficial distribution — not affiliated with Cloudflare.