Skip to main content
Glama
Cloudflare Workers MCP Server

Cloudflare Workers MCP Server

README.md
# Cloudflare Workers MCP Server

[![npm version](https://img.shields.io/npm/v/cloudflare-workers-mcp.svg)](https://www.npmjs.com/package/cloudflare-workers-mcp)
[![Tests](https://github.com/daniil-shumko/cloudflare-workers-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/daniil-shumko/cloudflare-workers-mcp/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](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

A3.7/5.0

Scored across 29 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count3/5

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.

Completeness4/5

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.

Maintenance

ActivityNo data
ResponsivenessOutdated data