# mcp-cloudflare [![GitHub release](https://img.shields.io/github/v/release/itunified-io/mcp-cloudflare?style=flat-square)](https://github.com/itunified-io/mcp-cloudflare/releases) [![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square)](LICENSE) [![CalVer](https://img.shields.io/badge/calver-YYYY.0M.DD.MICRO-22bfae?style=flat-square)](https://calver.org) [![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square)](https://nodejs.org) [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square)](https://www.typescriptlang.org/) [![mcp-cloudflare MCP server](https://glama.ai/mcp/servers/itunified-io/mcp-cloudflare/badges/card.svg)](https://glama.ai/mcp/servers/itunified-io/mcp-cloudflare) Slim Cloudflare MCP Server for managing DNS, zones, tunnels, WAF, Zero Trust, and security via Cloudflare API v4. **No SSH. No shell execution. API-only. 3 runtime dependencies.** ## Table of Contents - [Features](#features) - [Quick Start](#quick-start) - [Claude Code Integration](#claude-code-integration) - [Configuration](#configuration) - [Multi-Zone Support](#multi-zone-support) - [Tools](#tools) - [Skills](#skills) - [Development](#development) - [License](#license) ## Features 75 tools across 11 domains: - **DNS** — Record management (A, AAAA, CNAME, MX, TXT, SRV, CAA, NS), batch operations - **Zones** — Zone listing, settings, SSL/TLS configuration, cache management - **Tunnels** — Cloudflare Tunnel creation, configuration, and ingress management - **WAF** — Ruleset management, custom firewall rules, rate limiting - **Zero Trust** — Access application CRUD (create/delete), policies (create/delete), identity providers (create/delete), Gateway status - **Security** — Security event analytics, IP access rules, DDoS configuration, Security Center insights - **Workers KV** — Namespace management, key-value read/write/delete, key listing - **Workers** — Script deployment, route management - **Worker Secrets** — Secret management (names only, values never exposed) - **Worker Analytics** — Invocation metrics, CPU time, error rates via GraphQL - **R2 Storage** — Bucket management, object listing and metadata, custom domains, location hints ## Quick Start ```bash npm install cp .env.example .env # Edit with your Cloudflare API token npm run build node dist/index.js # stdio transport for MCP ``` ## Claude Code Integration Add to `.mcp.json` in your project root: ```json { "mcpServers": { "cloudflare": { "command": "node", "args": ["/path/to/mcp-cloudflare/dist/index.js"], "env": { "CLOUDFLARE_API_TOKEN": "your-api-token-here", "CLOUDFLARE_ACCOUNT_ID": "your-account-id" } } } } ``` ## Configuration | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `CLOUDFLARE_API_TOKEN` | Yes | — | Cloudflare API Token (with appropriate permissions) | | `CLOUDFLARE_ACCOUNT_ID` | No | — | Cloudflare Account ID (required for account-level operations) | | `CLOUDFLARE_TIMEOUT` | No | `30000` | Request timeout in milliseconds | | `NAS_VAULT_ADDR` | No | — | HashiCorp Vault URL, enables Vault AppRole loading (see below) | | `NAS_VAULT_ROLE_ID` | No | — | Vault AppRole role_id | | `NAS_VAULT_SECRET_ID` | No | — | Vault AppRole secret_id | | `NAS_VAULT_KV_MOUNT` | No | `kv` | Vault KV v2 mount path | ### Loading Secrets from HashiCorp Vault (AppRole) If you run a central Vault instance, `mcp-cloudflare` can fetch its credentials at startup via AppRole instead of passing them through the MCP config: ```sh export NAS_VAULT_ADDR=https://vault.example.com export NAS_VAULT_ROLE_ID= export NAS_VAULT_SECRET_ID= # optional — defaults to "kv" export NAS_VAULT_KV_MOUNT=kv ``` The loader reads KV v2 at `/data/cloudflare/api` and expects two keys: `api_token` and `account_id`. Example Vault write: ```sh vault kv put kv/cloudflare/api \ api_token=your-api-token-here \ account_id=00000000000000000000000000000000 ``` **Precedence:** `process.env` (explicit) > Vault. If `NAS_VAULT_ADDR` is unset the loader is a silent no-op — the server behaves exactly as before. On any Vault error (network, auth, missing path), a single-line warning is written to stderr and the server falls back to whatever env vars are already set. **Security:** secret values are never logged. Only the KV path name and a populated-count appear in stderr diagnostics. Uses the global `fetch` (Node 20+) — no new runtime dependencies. ### API Token Permissions Create an API Token at `dash.cloudflare.com/profile/api-tokens` with the following permissions based on what you need: - **DNS**: Zone > DNS > Edit - **Zone settings**: Zone > Zone Settings > Edit - **Cache purge**: Zone > Cache Purge > Edit - **Tunnels**: Account > Cloudflare Tunnel > Edit - **WAF**: Zone > Firewall Services > Edit - **Zero Trust**: Account > Access: Apps and Policies > Edit - **Security events**: Zone > Analytics > Read - **Workers KV**: Account > Workers KV Storage > Edit - **Workers**: Account > Worker Scripts > Edit - **R2**: Account > R2 Storage > Edit ## Multi-Zone Support All zone-scoped tools accept a `zone_id` parameter that can be either: - A **32-character hex zone ID** (e.g., `00000000000000000000000000000001`) — used directly - A **zone name / domain** (e.g., `example.com`) — resolved automatically via the Cloudflare API This allows managing multiple zones by name without needing to look up IDs manually. ## Tools Tools documentation is coming in v1 as tool modules are implemented. See [docs/api-reference.md](docs/api-reference.md) for the planned API endpoint mapping. ## Skills Claude Code skills compose MCP tools into higher-level workflows. See [`.claude/skills/README.md`](.claude/skills/README.md) for detailed documentation. | Skill | Slash Command | Description | |-------|--------------|-------------| | cloudflare-health | `/cf-health` | Zone health dashboard — DNS, security, tunnels, WAF, DDoS status | | cloudflare-live-test | `/cf-test` | Live integration test — read + safe writes with cleanup | | cloudflare-dns-management | — | DNS record management — add, list, update, delete across zones | | cloudflare-incident-response | — | DDoS/attack emergency response — detect, assess, mitigate, monitor | | cloudflare-security-audit | — | Security posture audit — WAF, events, IP access, DDoS analytics | | cloudflare-tunnel-management | — | Tunnel management — create, configure ingress, monitor connections | | cloudflare-waf-management | — | WAF management — custom rules, rulesets, IP access, Under Attack | | cloudflare-zero-trust | — | Zero Trust — access apps, policies, identity providers, gateway | | cloudflare-kv-manage | — | Workers KV — namespace and key-value CRUD operations | | cloudflare-worker-deploy | — | Workers — script deployment, routes, secrets, analytics | | cloudflare-r2-manage | — | R2 Storage — bucket and object management, audit workflows | ## Development ```bash npm run build # Compile TypeScript npm test # Run unit tests (vitest) npm run typecheck # Type check only (no emit) ``` See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines. ## License This project is dual-licensed: - **Open Source**: [GNU Affero General Public License v3.0 (AGPL-3.0)](LICENSE) — free for open-source and non-commercial use - **Commercial**: Available for proprietary integrations — see [COMMERCIAL_LICENSE.md](COMMERCIAL_LICENSE.md) If you use mcp-cloudflare in a proprietary product or SaaS offering, a commercial license is required. Support development by [sponsoring us on GitHub](https://github.com/sponsors/itunified-io).