cloudflare / cloudflare/mcp-server-cloudflare
npx/stdio server cannot run headless: 'run' requires Wrangler OAuth config file, and token-only invocation fails
- Dominant language
- TypeScript
- Stars
- 4.2k
- Forks
- 514
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 2
Description
## Summary
The stdio MCP server distributed as `@cloudflare/mcp-server-cloudflare` cannot be started headless (or in any container without an interactive browser) using a Cloudflare **API token**. It has two blocking failure modes, both reproduced with `@cloudflare/mcp-server-cloudflare@0.2.0`:
1. Invoked with **no subcommand** (as the README's stdio transport implies):
```
npx -y @cloudflare/mcp-server-cloudflare@0.2.0
→ Error: Unknown command: undefined. Expected 'init' or 'run'.
```
2. Invoked with **`run`** and `CLOUDFLARE_API_TOKEN`/`CLOUDFLARE_ACCOUNT_ID` exported:
```
→ Error: No config file found at ${XDG_CONFIG_HOME:-~}/.config/.wrangler/config/default.toml
```
## Reproduce (inside a container, no TTY)
```bash
CLOUDFLARE_API_TOKEN=test CLOUDFLARE_ACCOUNT_ID=test \
npx -y @cloudflare/mcp-server-cloudflare@0.2.0 \
<<< '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
# Error: Unknown command: undefined. Expected 'init' or 'run'.
CLOUDFLARE_API_TOKEN=test CLOUDFLARE_ACCOUNT_ID=test \
npx -y @cloudflare/mcp-server-cloudflare@0.2.0 run \
<<< '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
# Error: No config file found at /root/.config/.wrangler/config/default.toml
```
## Expected behaviour
A plain API token (the same credential used for the hosted servers, cf. #466) should be sufficient to start the stdio server for a client like Claude Code / Kimi Code / any MCP client, in an environment with **no browser and no interactive login**. The auth mechanism should prefer `CLOUDFLARE_API_TOKEN`/`CLOUDFLARE_ACCOUNT_ID` when present and not hard-fail on the absence of the OAuth token file.
Today the config file (`default.toml` with `oauth_token`/`refresh_token`) can only be produced by the interactive `npx wrangler login` OAuth flow, which requires a browser — impossible for headless/CI/container deployments. The README suggests the stdio transport can be configured with an API token (`CF_API_TOKEN`), but that path does not actually start the server.
## Impact
Any headless MCP client that registers this server via `npx @cloudflare/mcp-server-cloudflare` (the documented stdio approach) hits an unrecoverable startup failure unless someone can first complete an interactive OAuth login on the target machine.
## Related
- #466 — documentation of static API-token auth for the hosted servers.
Contributor guide
Research direction
Start by reproducing the two npx invocations in the issue, then inspect the package's npx entry point, the `run` command, and the authentication path described in the README. Done means the stdio server starts headlessly with CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID, without requiring the Wrangler OAuth config file or an interactive browser.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- nodejs, typescript
- Domain
- api, authentication, cli
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 58/100