Cloudflare Workers MCP Server
# Cloudflare Workers MCP Server
[](https://www.npmjs.com/package/cloudflare-workers-mcp)
[](https://github.com/daniil-shumko/cloudflare-workers-mcp/actions/workflows/test.yml)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
> ⚠️ **Security warning**: this server was substantially AI-written. Before
> pointing it at an account you care about: (1) review the code — it is small
> and readable, an audit takes ~30 minutes; (2) for maximum caution, clone and
> build from source rather than trusting the npm artifact (or at least pin an
> exact version); (3) give the API token the minimum permission
> (**Workers Scripts: Edit**) and nothing else; (4) prefer a test account for
> the first runs; (5) tools that take a local path (`directory`,
> `modules[].path`) upload whatever they point at to your Cloudflare account,
> where it can become publicly reachable, so keep your MCP client's approval
> prompts on for the deploy tools and check those paths before approving.
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for
managing Cloudflare Workers from Claude Desktop or Claude Code — the successor
to [cloudflare-pages-mcp](https://github.com/daniil-shumko/cloudflare-pages-mcp),
following Cloudflare's own shift from Pages to
[Workers with static assets](https://developers.cloudflare.com/workers/static-assets/).
## Why
As of mid-2026, no other MCP server — including Cloudflare's official ones —
can deploy a Worker. Cloudflare's remote MCP servers are read-only for Workers
management, and their Code Mode server has no filesystem so it can't upload
real asset trees. A local stdio server can: the Workers static-asset upload
protocol is [publicly documented](https://developers.cloudflare.com/workers/static-assets/direct-upload/),
so this server's headline feature is:
> *"Deploy this directory as a static site on Cloudflare Workers"* — in one
> natural-language request, with free unlimited static-asset serving.
## Tools
### Static sites (the differentiator)
- **deploy_static_site** - Deploy a local directory as a static site: manifest hashing, server-side dedupe (unchanged files never re-upload), `_headers`/`_redirects` support, SPA/404 handling, `base_path` URL prefix (where Cloudflare has enabled it for the account), live workers.dev URL in the result. Deploying over a Worker that has code replaces it with assets only, which removes its bindings and secrets (the result lists them in `secrets_dropped`)
- **redeploy_assets** - Redeploy reusing the live version's files and asset config, e.g. to bump the compatibility date. To change `html_handling`/`not_found_handling`/`base_path`, re-run `deploy_static_site`: unchanged files dedupe, so nothing re-uploads
### Previews (beta)
- **deploy_preview** - Deploy a preview of a site directory or Worker code without touching production, at a stable `https://<preview>-<worker>.<account>.workers.dev` URL plus a per-deployment URL. Redeploying the same `preview_name` updates it
- **list_previews / delete_preview** - List a Worker's previews with their URLs, or delete one by name
### Workers
- **list_workers** - List all Workers in your account with created/modified/last-deployed times and workers.dev/observability status
- **get_worker** - Settings (bindings, compat date/flags, placement, observability) plus cron triggers and workers.dev status
- **get_worker_code** - Download a Worker's deployed source (all modules)
- **deploy_worker** - Upload and deploy ES-module Workers with bindings (`plain_text`, `secret_text`, `kv_namespace`, `r2_bucket`, `d1`, `assets`). Each module is inline `content` or a local file `path` (bundled `.js`, `.wasm`, text/data), so large sources never pass through the conversation. Existing secrets are kept across redeploys
- **update_worker_settings** - Change bindings/compat/logpush/observability without re-uploading code (existing secrets are kept unless listed)
- **delete_worker** - Permanently delete a Worker (optional `force`)
### Secrets
- **list_secrets** - Secret names and types on a Worker (values are never returned)
- **set_secrets** - Set or delete several secrets in one new deployed version (`null` deletes) without touching code or other bindings
- **delete_secret** - Remove one secret
### Versions & deployments
- **list_versions / get_version** - Immutable version history and per-version detail
- **create_version** - Staged upload that does NOT touch live traffic
- **list_deployments / create_deployment** - Map traffic to versions: single version at 100% or gradual splits (e.g. 90/10)
- **rollback_worker** - Deploy an older version back to 100% traffic
### Domains, routing, cron
- **list_worker_domains / add_worker_domain / delete_worker_domain** - Custom domains (zone must be active in your account)
- **set_workers_dev** - Enable/disable `<name>.<account>.workers.dev` serving and version preview URLs
- **get_cron_triggers / set_cron_triggers** - Read or replace a Worker's cron trigger set
### Observability
- **tail_worker** - Live tail like `wrangler tail` for a short window (up to 50 s): requests, `console.log` output, exceptions and outcomes. Works on any Worker. Pass `trigger_url` to send a request once connected and capture it in the same call
- **query_worker_logs** - Workers Logs with time window, error filter, full-text search, and cursor paging to older events (`next_cursor`). Requires observability enabled on the Worker
- **health_check** - Verify API token and connection to Cloudflare
## Quick Start
Requires **Node.js 22+**.
**Option A: install from npm**
```bash
npm install -g cloudflare-workers-mcp
```
**Option B: clone and build locally (for code review)**
```bash
git clone https://github.com/daniil-shumko/cloudflare-workers-mcp
cd cloudflare-workers-mcp
npm install
npm run build
npm test # unit + MCP protocol smoke, no creds needed
```
### Configure Claude Desktop/Code
Create an API token with **Workers Scripts: Edit** (the "Edit Cloudflare
Workers" template works; both user and account-owned tokens are fine), find
your account ID in the [dashboard](https://dash.cloudflare.com), then:
```json
{
"mcpServers": {
"cloudflare-workers": {
"command": "npx",
"args": ["cloudflare-workers-mcp"],
"env": {
"CLOUDFLARE_API_TOKEN": "your_token_here",
"CLOUDFLARE_ACCOUNT_ID": "your_account_id_here"
}
}
}
}
```
(If you built from source, use `"command": "node"` with
`"args": ["/absolute/path/to/cloudflare-workers-mcp/dist/index.js"]` instead.)
Or with the Claude Code CLI:
```bash
claude mcp add cloudflare-workers \
-e CLOUDFLARE_API_TOKEN=your_token_here \
-e CLOUDFLARE_ACCOUNT_ID=your_account_id_here \
-- npx cloudflare-workers-mcp
```
## Usage Examples
```
Deploy the ./dist folder as a static site called my-blog
```
```
Deploy ./build as an SPA — client-side routing should fall back to index.html
```
```
Deploy this worker script with a KV binding for CACHE (namespace abc123)
```
```
Stage the new version without deploying, then roll it out 10% / 90%
```
```
Roll my-api back to the previous version
```
```
Attach app.example.com to my-api and add a cron trigger every 30 minutes
```
```
Show me the errors my-api logged in the last 2 hours
```
```
Tail my-api while you hit /checkout and tell me why it throws
```
```
Deploy ./dist as a preview of my-blog called redesign
```
```
Rotate STRIPE_KEY on my-api and remove the old LEGACY_TOKEN secret
```
## Important Notes
### Static site deploys
- Unchanged files are **deduped server-side**: redeploying an identical
directory uploads zero bytes and still creates a new version.
- A `_headers` or `_redirects` file at the directory root is applied as
configuration ([syntax](https://developers.cloudflare.com/workers/static-assets/headers/)),
not uploaded as a public asset. A root `.assetsignore` is applied with
gitignore-style rules (globs, `!` negation, `dir/` and `/anchored`
patterns; character classes unsupported) and the result reports how many
files it excluded.
- Limits: 25 MiB per file; 20,000 files per version on free plans
(100,000 on paid). Static-asset requests are free and unmetered.
- Symlinks inside the directory are followed; symlinks pointing outside it
abort the deploy.
### Versions & rollouts
- `create_version` stages code; only `create_deployment` (or a direct
deploy) shifts traffic. Gradual rollouts split across at most two
versions and percentages must sum to 100.
- Rollbacks reach the 100 most recent versions and never revert data in
bound resources (KV, R2, D1); a changed secret blocks rollback unless
`force` is set.
- Tools that build on the current version (`redeploy_assets`,
`deploy_worker`/`create_version` with `keep_assets`, and binding or
compatibility changes in `update_worker_settings`) **refuse while a
staged version or a gradual rollout is pending**. Otherwise the staged code
would silently become the base. Deploy or roll back first with
`create_deployment`.
- Cloudflare also blocks secret edits while the newest version isn't the
deployed one, for example right after a rollback (error 10215). Redeploy with
`deploy_worker` or deploy the newest version, then retry.
### Domains & serving
- Custom domains require the zone to be **active in the same Cloudflare
account** — external/partial zones are not supported (unlike Pages).
- Deploy tools enable workers.dev serving for **newly created** Workers so
the result carries a working URL. Redeploys never change an existing
Worker's workers.dev setting unless `enable_workers_dev` is passed
explicitly — a deliberately disabled Worker stays private.
- When `compatibility_date` is omitted, deploys **preserve the existing
Worker's pinned date** (new Workers get today's date) — a redeploy never
silently activates newer runtime behavior.
### Cron & logs
- `set_cron_triggers` **replaces** the full trigger set; pass `[]` to clear.
- `query_worker_logs` needs the Worker uploaded with observability enabled
(`deploy_worker`'s `enable_observability`, or `update_worker_settings`).
Retention is 3 days (free) / 7 days (paid).
- `tail_worker` needs no setup but only sees traffic during its window, so use
`trigger_url` (https only, redirects not followed) or send traffic while it
runs. Request headers and `cf` metadata are dropped from the results.
### Secrets & previews
- Every `set_secrets` / `delete_secret` call creates **and deploys** a new
version. Secret values travel through the conversation, so for highly
sensitive values `wrangler secret put` keeps them out of it.
- Previews use Cloudflare's **beta** Worker Previews API and attach to an
existing Worker (deploy production first). `deploy_preview` turns on the
Worker's preview URLs (`previews_enabled`) if they are off. It never
changes production workers.dev serving.
## Development
```bash
npm run build # compile to dist/ (tsup, ESM)
npm run typecheck # tsc --noEmit
npm test # unit + protocol smoke — safe, no creds, CI-ready
npm run test:unit # pure-logic units, fully mocked fetch
npm run test:protocol # drives the built server over the MCP stdio wire
npm run test:live # guarded live e2e (CF_LIVE_TEST=1 + real creds)
```
See [test/README.md](test/README.md) for the test layering. The live e2e
deploys a throwaway `cf-mcp-test-*` site through the real server, verifies it
serves over HTTP, and always cleans up.
## Related Links
- [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) - Verified API reference, design decisions, milestone history
- [cloudflare-pages-mcp](https://github.com/daniil-shumko/cloudflare-pages-mcp) - The maintenance-mode predecessor for existing Pages projects
- [Workers static assets docs](https://developers.cloudflare.com/workers/static-assets/) - What this server wraps
- [Direct upload protocol](https://developers.cloudflare.com/workers/static-assets/direct-upload/) - The asset-upload flow behind `deploy_static_site`
## License
MIT License - see [LICENSE](LICENSE) for details.
TDQS
Scored across 29 tools
Most tools map to a distinct resource+action, and descriptions actively disambiguate the tricky pairs (deploy_worker vs create_version vs deploy_preview, tail_worker vs query_worker_logs). However, get_worker and get_version both return bindings/compatibility settings for overlapping scopes, and delete_secret is essentially a shortcut for set_secrets' null-delete path, creating minor redundancy.
The set overwhelmingly follows verb_noun (list_workers, create_deployment, add_worker_domain, rollback_worker, set_cron_triggers). Minor deviations: health_check reverses the order to noun_verb, and the secret tools mix plural and singular (list_secrets/set_secrets vs delete_secret), which slightly obscures that delete_secret is the same family.
29 tools is heavy, but the domain is genuinely broad (deploy, versions, deployments, domains, cron, secrets, logs, previews, static sites). Most tools earn their place, though a few (delete_secret, redeploy_assets) could be folded into existing operations to trim the surface.
Lifecycle coverage is strong: deploy, version, deployment, rollback, previews, domains, cron, secrets, logs, and auth health are all present. Notable gaps remain around zone route patterns (only custom domains are supported), deleting individual versions, and inspecting a specific deployment by ID.