Cloudflare Tools

cloudflare-tools

Cloudflare tools for coding agents: zones, DNS, analytics, Workers, Pages, storage and tunnels.

The tools need Node.js 24 or later. docs/conventions.md describes how the tools are named and how they behave.

Install

Install from a release, never from the default branch: a release is a tag whose commit carries the built dist/, and the default branch does not. In the commands below, is a release's version (1.2.3) and is the commit its tag names:

gh api repos/craft-agent/cloudflare-tools/commits/v<version> --jq .sha

OpenCode

OpenCode V2 takes the package and its options in opencode.json:

{

"plugins": [{ "package": "@craftsamo/cloudflare-tools@ ", "options": { "read_only": false } }], "permissions": [{ "action": "cloudflare_*", "resource": "*", "effect": "ask" }] }

OpenCode V1 takes the package as a string, or as a pair with its options:

{

"plugin": [["@craftsamo/cloudflare-tools@ ", { "read_only": false }]], "permission": { "cloudflare_*": "ask" } }

OpenCode allows any action no rule names, so the plugin's request is granted silently unless a rule says ask. Read tools never ask, so the cloudflare_* glob is safe.

The options are the settings. A toolset that is off by default is turned on by listing it in toolsets with the ones to keep, for example "options": { "toolsets": ["account", "zones", "dns", "workers", "pages", "email"] }.

V1 registers no skills. Unpack the package and copy its skills/* folders into ~/.config/opencode/skills/:

npm pack @craftsamo/cloudflare-tools@<version>

tar -xzf craftsamo-cloudflare-tools- .tgz mkdir -p ~/.config/opencode/skills cp -r package/skills/* ~/.config/opencode/skills/ rm -rf package craftsamo-cloudflare-tools- .tgz

Claude Code

claude plugin marketplace add craft-agent/cloudflare-tools#v<version>

claude plugin install cloudflare-tools@craft-agent

Codex

codex plugin marketplace add craft-agent/cloudflare-tools --ref v<version>

codex plugin add cloudflare-tools@craft-agent

Codex turns - into _ in server names, so it shows the tools as mcp__cloudflare_tools__cloudflare_*. It starts the MCP server in the plugin's install directory and passes no roots, so the server takes each call's directory from what Codex sends with the call: its sandbox state, which the server asks for, else the one workspace it names.

The plugin declares default_tools_approval_mode = "writes": Codex asks before every tool not marked read-only. A user's [plugins." ".mcp_servers. ] setting can only tighten it. Setting auto there yields prompt (reads asked too), since Codex treats auto and writes as incomparable.

Grok Build

grok plugin install craft-agent/cloudflare-tools@v<version> --trust

Grok starts the MCP server in the session's working directory.

Antigravity

Install from the tree of the release tag, never from the default branch, which has no built dist/; Antigravity clones the tag into ~/.gemini/config/plugins/cloudflare-tools.

agy plugin install https://github.com/craft-agent/cloudflare-tools/tree/v<version>

Hermes Agent

Hermes installs a commit, not a tag, and the plugin installs disabled:

hermes plugins install craft-agent/cloudflare-tools --ref <sha>

hermes plugins enable cloudflare-tools

Hermes scans a plugin when it installs it. From v0.7.0 the verdict is caution: the tunnel tools name the token permission Account → Cloudflare One Connector: cloudflared, and Hermes rates the word as a tunneling service. hermes plugins install then asks before installing; where it cannot ask (no terminal), add --force, which overrides a caution verdict and no other.

If a Hermes gateway is already running, restart it (hermes gateway restart) to load the plugin.

The plugin runs the Node it found when Hermes started. If a version manager removes that version while Hermes runs, a call looks for Node again; when it finds none, restart Hermes from a shell where node runs.

When the package's writes depend on another Hermes plugin, such as a guard that blocks writes no one is there to approve, name it in require_plugins. Hermes keeps loading this plugin when that one fails to import or register, and treats a manifest's requires_plugins as advisory. With the setting, while a named plugin is not loaded, every write is refused before it is approved, even under --yolo, approvals.mode: off or a remembered answer, naming the plugin that is missing. Reads still run.

plugins:

entries: cloudflare-tools: settings: require_plugins: [write-guard]

Any other MCP host

Add the server to the host's MCP configuration. Flags go in args:

{

"mcpServers": { "cloudflare-tools": { "command": "npx", "args": ["-y", "@craftsamo/cloudflare-tools@ ", "--read-only"] } } }

Tools and skills

Confirmations described below apply to attended runs. With unattended on, a write runs without asking only under a grant that covers it; otherwise it is refused. See Writes no one is there to approve.

Each toolset comes with a skill that tells an agent how to use its tools. A skill names its toolset under metadata in its frontmatter (metadata: { toolset: dns }, written as a block). OpenCode V2 and Hermes register it only when the settings register at least one of that toolset's tools, so a profile with the toolset off, or with all its tools removed, does not see it; a skill without a toolset is always registered. Claude Code, Codex, Grok Build and Antigravity install the skill folder whole and pass the settings only to the MCP server, so they list every skill whatever the settings select. OpenCode V1 registers no skills, and its copied skills are all listed too.

Account (account)

Account credentials, token verification, and audit logs.

The skill is cloudflare-account, shown as cloudflare-tools:cloudflare-account in Claude Code and cloudflare-tools:account in Hermes.

Zones (zones)

Zone lookup, settings (read and change), Universal SSL, certificates, and DNSSEC.

The skill is cloudflare-zones, shown as cloudflare-tools:cloudflare-zones in Claude Code and cloudflare-tools:zones in Hermes.

DNS (dns)

DNS records: list, read one in full, export the zone file, add records, change them, and delete them.

The skill is cloudflare-dns, shown as cloudflare-tools:cloudflare-dns in Claude Code and cloudflare-tools:dns in Hermes.

Rules (rules)

Rules: read which rule phases of a zone hold rules and the rules of one phase in order, with their ids, positions and versions; add, change, move or delete a Single Redirect, Cache Rule, Configuration Rule, URL Rewrite Rule, Request or Response Header Transform Rule, Origin Rule or Compression Rule. WAF custom rules, rate limiting rules and custom error rules can be read but not changed. Expressions, descriptions and parameters are the user's data, returned as data and never instructions. This toolset is off by default; turn it on with the toolsets setting (see Settings).

| cloudflare_rules_delete | delete a rule of a phase; always asks first | admini