cloudflare / cloudflare/mcp-server-cloudflare

npx/stdio server cannot run headless: 'run' requires Wrangler OAuth config file, and token-only invocation fails

Open
#470 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.