# Cloudflare MCP Gateway

A centralized MCP (Model Context Protocol) gateway that aggregates multiple Cloudflare MCP services into a single unified server. Configure which services you need via environment variables and access them all through one MCP connection.

## Features

- **Unified Access**: Single MCP server for multiple Cloudflare services
- **Configurable Services**: Enable only the services you need via `ENABLED_SERVICES`
- **Dual Transport Support**: Works with both stdio (Claude Desktop) and streamable HTTP (web clients)
- **Tool Namespacing**: Automatic prefixing prevents tool name collisions (e.g., `kv_get`, `r2_list`)
- **Graceful Degradation**: Continues operating if some upstream services are unavailable

## Supported Services

| Service ID | Name | Description |
|------------|------|-------------|
| `docs` | Documentation | Cloudflare documentation reference and search |
| `bindings` | Workers Bindings | Storage, AI, and compute primitives for Workers |
| `builds` | Workers Builds | Deployment insights and management |
| `observability` | Observability | Logs and analytics debugging |
| `radar` | Radar | Internet traffic insights and URL scanning |
| `browser` | Browser Rendering | Web page fetching, markdown conversion, screenshots |
| `ai-gateway` | AI Gateway | Prompt/response log search and analysis |
| `d1` | D1 | Serverless SQL database operations |
| `kv` | KV | Key-value storage operations |
| `r2` | R2 | Object storage operations |

## Installation

```bash
# Using pip
pip install cf-mcp-gateway

# Using uv
uv pip install cf-mcp-gateway
```

## Quick Start

### 1. Get Cloudflare Credentials

You'll need:
- **API Token**: Create one at [Cloudflare Dashboard](https://dash.cloudflare.com/profile/api-tokens)
- **Account ID**: Found in your Cloudflare dashboard URL or account settings

### 2. Configure Environment

Create a `.env` file or set environment variables:

```bash
# Required
CLOUDFLARE_API_TOKEN=your-api-token
CLOUDFLARE_ACCOUNT_ID=your-account-id
ENABLED_SERVICES=docs,kv,r2

# Optional
TRANSPORT=stdio  # or streamable-http
LOG_LEVEL=info
```

### 3. Run the Gateway

```bash
# Using the CLI
cf-mcp-gateway

# Or as a Python module
python -m cf_mcp_gateway
```

## Usage with MCP Clients

### Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "cloudflare": {
      "command": "python",
      "args": ["-m", "cf_mcp_gateway"],
      "env": {
        "CLOUDFLARE_API_TOKEN": "your-api-token",
        "CLOUDFLARE_ACCOUNT_ID": "your-account-id",
        "ENABLED_SERVICES": "docs,kv,r2,d1",
        "TRANSPORT": "stdio"
      }
    }
  }
}
```

### Cursor

Add to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "cloudflare": {
      "command": "cf-mcp-gateway",
      "env": {
        "CLOUDFLARE_API_TOKEN": "your-api-token",
        "CLOUDFLARE_ACCOUNT_ID": "your-account-id",
        "ENABLED_SERVICES": "docs,bindings,observability"
      }
    }
  }
}
```

### Streamable HTTP (Remote/Web Access)

Start the gateway with HTTP transport:

```bash
CLOUDFLARE_API_TOKEN=xxx \
CLOUDFLARE_ACCOUNT_ID=yyy \
ENABLED_SERVICES=docs,kv,r2 \
TRANSPORT=streamable-http \
GATEWAY_HOST=0.0.0.0 \
GATEWAY_PORT=3000 \
cf-mcp-gateway
```

The server exposes:
- `POST /mcp` - MCP JSON-RPC endpoint
- `GET /health` - Health check endpoint

## Configuration Reference

### Required Environment Variables

| Variable | Description |
|----------|-------------|
| `CLOUDFLARE_API_TOKEN` | Your Cloudflare API token |
| `CLOUDFLARE_ACCOUNT_ID` | Your Cloudflare account ID |
| `ENABLED_SERVICES` | Comma-separated list of service IDs to enable |

### Optional Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `TRANSPORT` | `stdio` | Transport mode: `stdio` or `streamable-http` |
| `GATEWAY_HOST` | `0.0.0.0` | HTTP bind host (streamable-http only) |
| `GATEWAY_PORT` | `3000` | HTTP port (streamable-http only) |
| `CORS_ORIGINS` | `` | Allowed CORS origins, comma-separated |
| `LOG_LEVEL` | `info` | Logging level: debug, info, warning, error |

## Tool Naming Convention

Tools from upstream services are prefixed with their service ID to avoid collisions:

- `kv_get` - Get value from KV
- `kv_put` - Put value to KV
- `r2_list` - List R2 objects
- `r2_get` - Get R2 object
- `docs_search` - Search Cloudflare documentation

## Architecture

```
┌─────────────────┐     ┌─────────────────────────────────┐
│   MCP Client    │────▶│   Cloudflare MCP Gateway        │
│ (Claude, etc.)  │     │                                 │
└─────────────────┘     │  ┌─────────────────────────┐    │
                        │  │   Tool Aggregator       │    │
                        │  │   - Namespacing         │    │
                        │  │   - Request routing     │    │
                        │  └─────────────────────────┘    │
                        └──────────────┬──────────────────┘
                                       │
           ┌───────────────────────────┼───────────────────────────┐
           ▼                           ▼                           ▼
┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│ docs.mcp.cf.com  │      │  kv.mcp.cf.com   │      │  r2.mcp.cf.com   │
└──────────────────┘      └──────────────────┘      └──────────────────┘
```

## License

MIT License - see LICENSE file for details.
