# brave-search-mcp-cloudflare

A remote [MCP](https://modelcontextprotocol.io/) server that wraps the official [Brave Search MCP server](https://github.com/brave/brave-search-mcp-server) and deploys it as a Cloudflare Worker with Durable Objects.

The official repo supports only stdio/Express transports. This project makes it a proper **remote** MCP server reachable over HTTP — usable by any MCP-compatible client without running a local process.

## Tools

All 6 Brave Search tools are available:

| Tool | Description |
|------|-------------|
| `brave_web_search` | General web search |
| `brave_news_search` | News search |
| `brave_image_search` | Image search |
| `brave_video_search` | Video search |
| `brave_local_search` | Local/maps search with POIs and descriptions |
| `brave_summarizer` | AI-powered search summarization |

## Architecture

- **Runtime**: Cloudflare Workers with Durable Objects (for `McpAgent` state)
- **MCP SDK**: `McpAgent` from `agents` package + `McpServer` from `@modelcontextprotocol/sdk`
- **Auth**: Cloudflare Access (Zero Trust) — protects `/mcp` endpoint
- **API key**: Stored as a Wrangler secret (`BRAVE_API_KEY`), never committed

## Deployment

### Prerequisites

- [Cloudflare account](https://dash.cloudflare.com/sign-up)
- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) authenticated (`wrangler login`)
- [Brave Search API key](https://brave.com/search/api/)

### Deploy

```bash
npm install

# Set your Brave Search API key as a secret
wrangler secret put BRAVE_API_KEY

# Deploy to Cloudflare Workers
npm run deploy
```

The Worker will be available at `https://brave-search-mcp-cloudflare.<your-subdomain>.workers.dev`.

### Health check

```bash
curl https://brave-search-mcp-cloudflare.<your-subdomain>.workers.dev/health
# {"status":"ok"}
```

## Cloudflare Access Setup (recommended)

To protect the `/mcp` endpoint so only authorized clients can connect:

1. Go to [Zero Trust dashboard](https://one.dash.cloudflare.com/) → **Access** → **Applications**
2. Click **Add an application** → **Self-hosted**
3. Set the application domain to your Worker URL with path `/mcp`
4. Create a policy (e.g., allow specific email domains, or use Service Tokens for programmatic access)
5. To create a Service Token: **Access** → **Service Auth** → **Service Tokens** → **Create Service Token**

### Connecting an MCP client through Cloudflare Access

Use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) with your Service Token credentials:

```json
{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://brave-search-mcp-cloudflare.<your-subdomain>.workers.dev/mcp",
        "--header",
        "CF-Access-Client-Id:<your-client-id>",
        "--header",
        "CF-Access-Client-Secret:<your-client-secret>"
      ]
    }
  }
}
```

## Local development

```bash
# Set your API key in .dev.vars (never commit this file)
echo "BRAVE_API_KEY=your_key_here" > .dev.vars

npm run dev
# Worker available at http://localhost:8787
# MCP endpoint: http://localhost:8787/mcp
```

Test with [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
```bash
npx @modelcontextprotocol/inspector http://localhost:8787/mcp
```

## License

MIT — see [LICENSE](./LICENSE)