Skip to content
MCP server

Surfbird MCP

Self-hosted headless browser tools: markdown, screenshots, PDF and batch fetch

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
self-hosted, API, Linux
Runs
Locally
Version
0.1.2
Listing updated
today

Similar MCP servers

About Surfbird MCP

Surfbird MCP is an open-source MCP server for browser automation. It runs locally on your machine and is started by your AI client.

Surfbird is an unofficial Docker distribution of Cloudflare's experimental Kitesurf engine, which parses HTML, applies CSS, runs page JavaScript and renders screenshots without Chrome. This MCP wrapper talks to the Surfbird REST proxy, so an agent on your own VPS gets browser actions without a separate browser container.

It adds surf_markdown and surf_batch, which the README says stock browser MCPs lack. Batch runs one action over up to 20 URLs by default with per-item results. Configuration is through SURFBIRD_URL, a bearer SURFBIRD_TOKEN and a per-tool timeout. The server image supports URL allowlists and blocklists, a cap on concurrent actions and request body size, and optional TLS.

Limits come from the upstream engine: it is experimental, heavy-JavaScript sites may render imperfectly, and there are no touch gestures, video decoding or file downloads. The auth image is a token gate, not a multi-tenant boundary, and the raw image should never be exposed. Apache-2.0 licensed; not affiliated with Cloudflare.

Install

Run in a terminal

claude mcp add surfbird-mcp --env SURFBIRD_TOKEN='<SURFBIRD_TOKEN>' -- npx -y surfbird-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "surfbird-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "surfbird-mcp"
      ],
      "env": {
        "SURFBIRD_TOKEN": "<SURFBIRD_TOKEN>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "surfbird-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "surfbird-mcp"
      ],
      "env": {
        "SURFBIRD_TOKEN": "<SURFBIRD_TOKEN>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "surfbird-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "surfbird-mcp"
      ],
      "env": {
        "SURFBIRD_TOKEN": "<SURFBIRD_TOKEN>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "surfbird-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "surfbird-mcp"
      ],
      "env": {
        "SURFBIRD_TOKEN": "<SURFBIRD_TOKEN>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "surfbird-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "surfbird-mcp"
      ],
      "env": {
        "SURFBIRD_TOKEN": "<SURFBIRD_TOKEN>"
      }
    }
  }
}

Using several servers? Build one config file with the MCP config generator.

Configuration

  • SURFBIRD_URLBase URL of the Surfbird auth-image REST proxy
  • SURFBIRD_TOKENBearer token matching SURFBIRD_TOKEN on the container
  • SURFBIRD_TIMEOUT_MSPer-tool timeout in milliseconds

Tools this server provides (8)

Taken from the project documentation; the running server may differ.

surf_markdown
Fetches a page as markdown.
surf_content
Returns the post-JavaScript rendered DOM.
surf_source
Returns the original response body.
surf_screenshot
Captures a screenshot.
surf_pdf
Renders a page to PDF.
surf_evaluate
Evaluates JavaScript in a page.
surf_batch
Runs one action over multiple URLs.
surf_health
Checks that the engine is responding.

What it does

Page to markdown
Converts a rendered page into markdown text.
Batch actions
Runs one action across many URLs with per-item results.
Screenshots and PDF
Captures full-page images or PDFs.
Rendered and source HTML
Returns the post-JavaScript DOM or the original response.
Script evaluation
Runs JavaScript in the page and returns the result.
URL allow and block lists
Restricts which addresses the browser may fetch.

Good for

  • Turn web pages into markdown for an agent
  • Screenshot many pages in one call
  • Run a headless browser on your own server
  • Build a feed-to-digest pipeline

Pricing

Open source

Surfbird MCP FAQ

Does it need Chrome?

No. It uses the Kitesurf engine, which renders without Chrome or a browser container.

Is it safe to expose publicly?

The README says never expose the raw image; the auth image needs a token plus firewall or TLS and is not multi-tenant hardened.

How do I authenticate?

Set `SURFBIRD_TOKEN` on the container and the same value in the MCP environment.

Is it affiliated with Cloudflare?

No. It is an unofficial distribution of the Apache-2.0 Kitesurf project.

Is Surfbird MCP free?

Yes. Surfbird MCP is open source, so you can use and self-host it for free.

How do I add Surfbird MCP to Claude Code?

Run this command in your terminal: claude mcp add surfbird-mcp --env SURFBIRD_TOKEN='<SURFBIRD_TOKEN>' -- npx -y surfbird-mcp

What are the best alternatives to Surfbird MCP?

The closest alternatives to Surfbird MCP are Browser Use, Scrapling MCP Server, Chrome DevTools MCP, Firecrawl MCP Server and Douyin_TikTok_Download_API.

Where this comes from

  • Description: written from the project's README.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers