# clawdflare

Opinionated Cloudflare MCP server — audit and fix your zones.

Read operations are free. Write operations require a PIN.

## The idea

AI agents are great at reading infrastructure and telling you what's wrong. They're less great at having unsupervised write access to your DNS and SSL settings. Clawdflare solves this by splitting access:

- **Read token** (env var) — the AI uses this freely to audit, inspect, and report
- **Write token** (encrypted on disk) — decrypted only when you enter a PIN into a macOS popup

The AI never sees the write token. It never sees the PIN. It gets back a success/failure result and that's it.

**[Full setup guide and security rationale →](SETUP.md)**

## Quick start

```bash
pip install -e ".[dev]"

# 1. Read-only token in your environment
export CLOUDFLARE_API_TOKEN="your-read-only-token"

# 2. Encrypt your write token with a PIN
clawdflare setup-token

# 3. Go
clawdflare audit example.com
```

## Usage

### CLI

```bash
clawdflare zones                    # list all zones
clawdflare audit example.com        # audit against best practices
clawdflare fix example.com          # dry-run: show what would change
clawdflare fix example.com --apply  # apply fixes (PIN required)
clawdflare ssl-status example.com   # SSL/TLS summary
clawdflare dns-records example.com  # list DNS records
clawdflare set-setting example.com ssl full  # set a setting (PIN required)
clawdflare purge-cache example.com --everything  # purge cache (PIN required)
```

### MCP Server

```bash
clawdflare serve
```

Add to Claude Code settings:

```json
{
  "mcpServers": {
    "clawdflare": {
      "command": "clawdflare",
      "args": ["serve"],
      "env": {
        "CLOUDFLARE_API_TOKEN": "your-read-only-token"
      }
    }
  }
}
```

## Opinions

Clawdflare ships with opinionated defaults for security and performance. Run `clawdflare audit` to see how your zone stacks up:

- **SSL**: Full mode (not flexible — flexible leaves origin traffic unencrypted)
- **HTTPS**: Always redirect, HSTS with 1-year max-age and subdomains
- **TLS**: Minimum 1.2 (1.0/1.1 are deprecated and vulnerable), TLS 1.3 with 0-RTT
- **HTTP/3**: Enabled (QUIC reduces latency, especially on mobile)
- **Cache**: 4-hour browser TTL
- **Security**: Email obfuscation, hotlink protection, automatic HTTPS rewrites

Every opinion includes a reason. Disagree? Override with `clawdflare set-setting`.

## Security model

| Operation | Token used | AI can see token? | Authorization |
|---|---|---|---|
| `zones`, `audit`, `dns-records`, `ssl-status`, `zone-settings` | Read (env var) | Yes | None needed |
| `fix --apply`, `set-setting`, `purge-cache` | Write (encrypted vault) | Never | PIN via macOS popup |

See [SETUP.md](SETUP.md) for the full threat model and rationale.
