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.

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, which is never the caller's working tree.

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

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

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

Each toolset comes with a skill that tells an agent how to use its tools.

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.

Adding a tool

1. Write the spec in src/core/ / .ts with defineTool: an ID _ _ , a title and description, the Zod argument and output schemas, its toolset and write class, and execute(args, context). A write tool also gives targets(args, context): what the call writes to, as a permission rule should name it.
2. Test it beside the spec ( .test.ts), calling it through invoke as the entry points do. A tool that runs a program is tested against a fake of that program on PATH; no test reaches a real service.
3. List it in src/tools.ts. A new toolset goes into toolsets in src/project.ts (and defaultToolsets when it is on by default).
4. Add or update the toolset's skill, skills/ - /SKILL.md.
5. Run pnpm run build && pnpm run manifests to list the tool in plugin.yaml, then describe it under "Tools and skills".

docs/conventions.md has the rules each step follows.

Reads and writes

Every read tool is named _ _read. Reads can run unasked; writes are confirmed by the harness.

Where a write is asked about, and where it is not:

• OpenCode grants any action no rule names, so a write runs unasked unless a rule asks for it: add the cloudflare_* rule shown under OpenCode.
• Codex under codex exec, and Grok Build under grok -p, refuse a write they cannot ask about, unless it is allowed beforehand.
• Grok Build calls the plugin's tools through its use_tool tool, and the agent often names a tool without its server first. Grok checks the rules against the name as given, so the server-qualified rule alone does not match that first call. The second rule matches the short name; a write still matches neither.
• Antigravity asks before any MCP tool no rule allows, reads included, and names the plugin's server cloudflare-tools_cloudflare-tools (plugin, then server). agy -p refuses a tool it cannot ask about.
• Hermes hermes chat -q refuses a write it cannot ask about; hermes -z and --yolo skip approval, so writes then run unasked.

Settings

Every entry point takes the same settings. A flag wins over its environment variable, and an option or setting wins over the variable too.

Lists are comma-separated in a flag or a variable. Where each harness reads them:

• OpenCode takes the plugin options shown above, with lists as arrays and read_only as a boolean.
• Hermes takes plugins.entries.cloudflare-tools.settings in config.yaml:

  plugins:

entries: cloudflare-tools: settings: read_only: false exclude_tools: []

• Claude Code and Antigravity start the plugin's server without flags and pass it the client's environment, so set the variables in the environment the harness runs in.
• Codex and Grok Build pass no environment to a plugin's MCP server, so the variables have no effect there. To change settings in Codex, add the server under [mcp_servers] in Codex's config with flags in args (as in Any other MCP host) instead of using the plugin.

Credentials

The tools call Cloudflare with API tokens read from the environment, never from a setting or an argument. Each token comes wi