cf-mcp-traffic

A local stdio MCP server that exposes Cloudflare HTTP traffic and firewall analytics to Claude Code. Query traffic by 20+ dimensions, drill into individual actors, and score suspicion against a documented rulebook. Includes a deterministic scorer so it can run without Claude. Local-only, not deployed.

What it exposes

Four MCP tools plus a helper:

• list_known_domains — the zones configured in your domains.json
• traffic_summary — aggregated bucket counts from httpRequestsAdaptiveGroups, grouped by up to 3 of ~20 dimensions (ASN, path, IP, JA4, country, status, bot_score_bucket, time_hour, etc.)
• firewall_events — same shape but on WAF / rate-limit / bot-management / custom-rule actions, with rule descriptions
• requests_for — sampled per-request drilldown, filtered by IP / JA4 / ASN / path / UA / status
• score_actor — runs the deterministic scorer against a pre-aggregated ActorSignals bundle

The scoring logic lives in src/lib/scoring.ts. It's a pure function — no I/O, no globals, importable from any TS runtime.

Prerequisites

• Bun installed locally
• A Cloudflare API token with Account Analytics:Read + Zone Analytics:Read on every zone you want to query. Generate at https://dash.cloudflare.com/profile/api-tokens.

Setup

1. Clone and install

git clone git@github.com:Greta221/cf-mcp-traffic.git
cd cf-mcp-traffic
bun install

2. Create your data directory

The server reads all account-specific config from a local directory pointed at by the CF_MCP_TRAFFIC_DATA_DIR env var. Nothing account-specific ships with the code.

mkdir -p ~/.cf-mcp-traffic-data

Populate two files inside it:

.env — your credentials:

CF_API_TOKEN=your_token_here
CF_ACCOUNT_ID=your_account_id_here

domains.json — a flat map from domain name to its Cloudflare zone tag:

{
  "example.com": "your_zone_tag_here",
  "another-example.com": "another_zone_tag"
}

Zone tags come from the Cloudflare dashboard: Zone overview → API → Zone ID.

3. Wire it into Claude Code

Add the server to ~/.claude.json (or the project-local .mcp.json):

{
  "mcpServers": {
    "cf-traffic": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "/absolute/path/to/cf-mcp-traffic/src/index.ts"],
      "env": {
        "CF_MCP_TRAFFIC_DATA_DIR": "/absolute/path/to/your/.cf-mcp-traffic-data"
      }
    }
  }
}

Restart Claude Code. The cf-traffic server should appear in /mcp.

Optional: watch list, trust list, site patterns

Two markdown files and one JSON, all in your data directory. Only needed if you use the /triage-traffic runbook (see below) or the score_actor tool with trust penalties.

• watch-list.md — actors observed misbehaving but not severe enough to block. Log the actor, the reason, and the trigger for revisiting.
• trust-list.md — known-good sources (payment webhooks, internal infra, verified crawlers). Membership drives negative penalties on scored actors.
• site-patterns.json — your account's API hosts, application URL patterns, sensitive POST endpoints. Drives several signals. Expected keys:

{
  "api_hosts": ["api.example.com"],
  "api_path_prefixes": ["/api/", "/v1/"],
  "html_paths": ["/", "/profile"],
  "asset_path_prefixes": ["/static/", "/assets/"],
  "asset_file_extensions": [".css", ".js", ".png"],
  "sensitive_post_paths": ["/login", "/checkout/pay"]
}

None of these files are required to boot the server. Signals that depend on missing files simply don't fire.

Running the scorer without Claude

The scorer is a pure function. Import and call it:

import { scoreActor } from "./src/lib/scoring";
import type { ActorSignals } from "./src/lib/types";

const input: ActorSignals = {
  identifier_type: "ip",
  identifier: "1.2.3.4",
  // ...populate the remaining fields from your own aggregations
};

const result = scoreActor(input);
console.log(result.score, result.reasons);

Signal names, weights, and thresholds are in src/lib/constants.ts. Input and output types are in src/lib/types.ts.

The scoring rulebook

The scoring policy (how signals fire, what they mean, how trust penalties work, worked examples) lives at .claude/commands/triage-traffic.md. It's a slash command Claude Code reads — you can invoke it with /triage-traffic inside Claude, or read it as documentation for the scoring model.

The rulebook and the code are kept in sync: rulebook signal names match the SIGNAL constants in src/lib/constants.ts.

Development

bun run test       # vitest, single run
bun run test:watch
bun run check      # biome lint + format check

Design notes

• Stdio MCP server, not a Worker. Runs locally on demand when Claude invokes a tool.
• requests_for returns sampled data (~1% on busy zones). Never use it for path or host counts — always use traffic_summary aggregations for those.
• The score_actor tool takes a pre-computed ActorSignals object. Aggregating the signals from raw traffic queries is the caller's job (Claude does this in-session by reading the rulebook and calling the query tools).