cf-mcp

Read-only Cloudflare MCP server for SOC investigation agents (companion to sumologic-mcp, flare-mcp, mcp-virustotal).

Exposes:

• Discovery — accounts, zones
• Rulesets & WAF — custom rules, rate-limit rules, managed rulesets
• Bot Management — config, Super Bot Fight Mode
• Analytics (GraphQL) — firewall events, HTTP requests, bot events, baseline traffic diff
• Cloudflare One / Zero Trust — Access apps & policies, Gateway rules, WARP devices, IdPs
• Logpush — job metadata
• Helpers — dashboard URL builder, wirefilter validator

v1 is strictly read-only. Every non-GET HTTP request is refused at the client layer when CF_READ_ONLY=true (default).

Install

uv sync

Configure

Store your Cloudflare API token in the OS credential store (Windows Credential Manager / macOS Keychain / Linux Secret Service):

uv run cf-mcp-setup

Alternatively, set the CF_API_TOKEN environment variable in your MCP client config — useful on headless Linux hosts where no keyring backend is available.

Required token scopes

Create an API token at https://dash.cloudflare.com/profile/api-tokens with at least these read permissions:

• Zone Read
• Zone WAF Read
• Account Rulesets Read
• Account Settings Read
• Bot Management Read
• Analytics Read (Account + Zone)
• Logs Read
• Access: Apps Read, Access: Policies Read
• Zero Trust: Gateway Read

Optional env vars

• CF_ACCOUNT_ID — default account ID for account-scoped tools.
• CF_ZONE_ALLOWLIST — comma-separated zone names; zone-scoped tools refuse zones not in the list, even if the token has broader access.
• CF_READ_ONLY — defaults to true; set false only if a future v1.5 ships mutating tools and you've reviewed them.

MCP client config

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "cloudflare": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/cf-mcp", "cf-mcp"],
      "env": {
        "CF_ACCOUNT_ID": "<your-account-id>",
        "CF_ZONE_ALLOWLIST": "example.com,example.net"
      }
    }
  }
}

Development

uv sync
uv run ruff check src tests
uv run mypy --strict src
uv run pytest tests/unit
CF_LIVE_TEST=true uv run pytest tests/integration

Architecture notes

• One async httpx client per process, shared across all tool calls.
• No retry on 429 — the agent decides; retry_after_s is surfaced in the error envelope. Retry 502/503/504 with exponential backoff + jitter, max 3 attempts, ~10s total budget.
• No internal rate-limit accountant — Cloudflare's edge and the agent are the only governors. REST quota is 1200/5min; GraphQL is a separate 300/5min.
• No cache in v1 — the cache_meta envelope field is reserved for v1.5.
• Compact-mode by default — GraphQL tools return only dimensions + counts. Detail drill-down via verbose=true on cf_query_firewall_events_raw and cf_query_http_requests_raw.
• Hard ~20K-token response ceiling — exceeding tools return response_too_large with a hint, never silent truncation.

Response envelope

{
  "data": {...},
  "next_cursor": "v1.<base64>",
  "cache_meta": {"hit": false, "age_s": 0, "ttl_s": 0},
  "api_endpoint_called": "POST /graphql",
  "correlation_id": "uuid",
  "error": null
}

On error, data is null and error has:

{
  "code": "rate_limited|auth|not_found|validation|upstream|response_too_large|read_only_violation|zone_not_allowed",
  "http_status": 429,
  "cf_errors": [{"code": 10000, "message": "..."}],
  "retry_after_s": 30,
  "hint": "narrow the time range or reduce limit"
}