# Surfbird MCP

> Surfbird MCP is an open-source MCP server for browser automation. Self-hosted headless browser tools: markdown, screenshots, PDF and batch fetch. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** self-hosted, API, Linux
- **Repository:** https://github.com/terry2010/surfbird
- **MCP Registry name:** io.github.terry2010/surfbird-mcp
- **Categories:** [browser automation](https://ai-powered.com/categories/browser-automation), [files and documents](https://ai-powered.com/categories/files-and-documents), [web search and scraping](https://ai-powered.com/categories/web-search-and-scraping)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `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.

## 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.

## Alternatives

- [Browser Use](https://ai-powered.com/mcp/browser-use): Browser Use is a freemium MCP server for browser automation.
- [Scrapling MCP Server](https://ai-powered.com/mcp/scrapling-mcp-server): Scrapling MCP Server is an open-source MCP server for web search and scraping.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Firecrawl MCP Server](https://ai-powered.com/mcp/firecrawl-mcp-server): Firecrawl MCP Server is a freemium MCP server for web search and scraping.
- [Douyin_TikTok_Download_API](https://ai-powered.com/mcp/douyin-tiktok-download-api): Douyin_TikTok_Download_API is an open-source MCP server for web search and scraping.
- [SearXNG Search](https://ai-powered.com/mcp/searxng-search): SearXNG Search is an open-source MCP server for web search and scraping.
- [Oya Browser](https://ai-powered.com/mcp/oya-browser): Oya Browser is a freemium MCP server for browser automation.
- [playwright_mcp](https://ai-powered.com/mcp/playwright-mcp-3): playwright_mcp is an open-source MCP server for browser automation.

---
Source: https://ai-powered.com/mcp/surfbird-mcp
