# cloudflare-mcp
> A smol MCP server for the complete Cloudflare API.
[](https://deploy.workers.cloudflare.com/?url=https://github.com/mattzcarey/cloudflare-mcp)
Uses codemode to avoid dumping too much context to your agent.
## Get Started
### Create API Token
Create a [Cloudflare API token](https://dash.cloudflare.com/profile/api-tokens) with the permissions you need.
Both **user tokens** and **account tokens** are supported:
| Token Type | Description | Requirements |
|------------|-------------|--------------|
| User Token | Created at user level, can access multiple accounts | Requires `account_id` parameter on each execute call |
| Account Token | Scoped to single account | `account_id` auto-detected, no parameter needed |
For account tokens, include the **Account Resources : Read** permission so the server can auto-detect your account ID.
### Add to Agent
MCP URL: `https://cloudflare-mcp.mattzcarey.workers.dev/mcp`
Bearer Token: Your [Cloudflare API Token](https://dash.cloudflare.com/profile/api-tokens)
#### Claude Code
<details>
<summary>CLI</summary>
```bash
export CLOUDFLARE_API_TOKEN="your-token-here"
claude mcp add --transport http cloudflare-api https://cloudflare-mcp.mattzcarey.workers.dev/mcp \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```
</details>
#### OpenCode
<details>
<summary>opencode.json</summary>
Set your API token as an environment variable:
```bash
export CLOUDFLARE_API_TOKEN="your-token-here"
```
Then add to your `opencode.json`:
```json
{
"mcp": {
"cloudflare-api": {
"type": "remote",
"url": "https://cloudflare-mcp.mattzcarey.workers.dev/mcp",
"headers": {
"Authorization": "Bearer {env:CLOUDFLARE_API_TOKEN}"
}
}
}
}
```
</details>
## The Problem
The Cloudflare OpenAPI spec is **2.3 million tokens** in JSON format. Even compressed to TypeScript endpoint summaries, it's still **~50k tokens**. Traditional MCP servers that expose every endpoint as a tool, or include the full spec in tool descriptions, leak this entire context to the main agent.
This server solves the problem by using **code execution** in a [codemode](https://blog.cloudflare.com/code-mode/) pattern - the spec lives on the server, and only the results of queries are returned to the agent.
## Tools
Two tools where the agent writes code to search the spec and execute API calls. Akin to [ACI.dev's MCP server](https://github.com/aipotheosis-labs/aci) but with added codemode.
| Tool | Description |
| --------- | ----------------------------------------------------------------------------- |
| `search` | Write JavaScript to query `spec.paths` and find endpoints |
| `execute` | Write JavaScript to call `cloudflare.request()` with the discovered endpoints |
**Token usage:** Only search results and API responses are returned. The 6MB spec stays on the server.
```
Agent MCP Server
│ │
├──search({code: "..."})───────►│ Execute code against spec.json
│◄──[matching endpoints]────────│
│ │
├──execute({code: "..."})──────►│ Execute code against Cloudflare API
│◄──[API response]──────────────│
```
## Supported Products
Workers, KV, R2, D1, Pages, DNS, Firewall, Load Balancers, Stream, Images, AI Gateway, Vectorize, Access, Gateway, and more. See the full [Cloudflare API schemas](https://github.com/cloudflare/api-schemas).
## Usage
Once configured, just ask your agent to do things with Cloudflare:
- "List all my Workers"
- "Create a KV namespace called 'my-cache'"
- "Add an A record for api.example.com pointing to 192.0.2.1"
The agent will search for the right endpoints and execute the API calls. Here's what happens behind the scenes:
```javascript
// 1. Search for endpoints
search({
code: `async () => {
const results = [];
for (const [path, methods] of Object.entries(spec.paths)) {
for (const [method, op] of Object.entries(methods)) {
if (op.tags?.some(t => t.toLowerCase() === 'workers')) {
results.push({ method: method.toUpperCase(), path, summary: op.summary });
}
}
}
return results;
}`,
});
// 2. Execute API call (user token - account_id required)
execute({
code: `async () => {
const response = await cloudflare.request({
method: "GET",
path: \`/accounts/\${accountId}/workers/scripts\`
});
return response.result;
}`,
account_id: "your-account-id",
});
// 2. Execute API call (account token - account_id auto-detected)
execute({
code: `async () => {
const response = await cloudflare.request({
method: "GET",
path: \`/accounts/\${accountId}/workers/scripts\`
});
return response.result;
}`,
});
```
## Token Comparison
| Content | Tokens |
| ----------------------------- | ---------- |
| Full OpenAPI spec (JSON) | ~2,352,000 |
| Endpoint summary (TypeScript) | ~43,000 |
| Typical search result | ~500 |
| API response | varies |
## Architecture
```
src/
├── index.ts # MCP server entry point
├── server.ts # Search + Execute tools
├── executor.ts # Isolated worker code execution
├── truncate.ts # Response truncation (10k token limit)
└── data/
├── types.generated.ts # Generated endpoint types
├── spec.json # OpenAPI spec for search
└── products.ts # Product list
```
Code execution uses Cloudflare's Worker Loader API to run generated code in isolated workers, following the [codemode pattern](https://github.com/cloudflare/agents/tree/main/packages/codemode).
## Development
```bash
npm i
npm run deploy
```
