# workers-mcp turns a Cloudflare Worker into an MCP tool server

> workers-mcp is a build step and a local Node.js proxy that translates the public methods of a Cloudflare Worker into MCP tools, so Claude Desktop or another MCP client can call a function running on the edge. The project itself points new users at a remote MCP server instead, and that recommendation deserves attention.

**cloudflare/workers-mcp** — Talk to a Cloudflare Worker from Claude Desktop!

- Repository: https://github.com/cloudflare/workers-mcp
- Website: https://www.npmjs.com/package/workers-mcp
- Stars: 646 · Forks: 67
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/cloudflare-workers-mcp

## The project asks you not to use it for new projects

The very first thing the readme says, above the description, is a warning, and it is unusual enough to lead with it. You should start with the remote MCP server guide instead and build a remote MCP server, and the package is described as something for connecting to remote MCP servers from Claude Desktop, Cursor and other clients using mcp-remote. That is the maintainers of a Cloudflare package telling you that the local proxy approach has been superseded. Any evaluation should take that at face value. The package is still published on npm, the code is in the repository, and the setup flow described below still works, but the direction of travel is clear. The local route exists because it solves a real problem, namely getting a function of a Worker callable from a desktop client without standing up a server of your own, and it solves it with a process on your own machine. If you are starting from nothing, the remote pattern is the one to learn.

## A build step reads your Worker class and emits tools

The mechanism is a source transform, and that is the technically interesting part. The package provides both the CLI tooling and the in-Worker logic, and it works via a build step that can translate TypeScript methods of your Worker into MCP tools that a local Node.js server can expose to MCP clients. The input is an ordinary Worker class, a class extending WorkerEntrypoint with typed methods:

```ts
export class ExampleWorkerMCP extends WorkerEntrypoint<Env> {
  async getRandomNumber() {
    return `Your random number is ${Math.random()}`
  }
```

The dependency list explains how the extraction works. jsdoc-api pulls the doc comments, ts-blank-space and just-filter-object and just-map-values narrow the parsed output, and tsx runs the transform. The doc comments are not decoration, they are the input the tool uses to build the tool descriptions that a language model will read, which is why the example carries a return annotation. The claim in the readme is wide, that this allows you to expose any function or API in your app, or any service in Cloudflare's developer platform, back to a LLM in your coding agent, Claude Desktop or other MCP client. In practice the exposure is bounded by what a public method on the Worker class does, since the transform operates on the class you hand it.

## The runtime shape is a local proxy speaking stdio

The transport arrangement is the part to understand before configuring a client. The Node.js server acts as a proxy, handling stdio transport locally, and calling the relevant method of your Worker running on Cloudflare. So there are two processes in the picture. Your MCP client spawns the local Node server and talks to it over stdio, and the server makes network calls to the deployed Worker over HTTPS. The proxy is what lets a stdio-only client reach something that lives behind an HTTPS URL at a workers.dev address, and it is also what adds a moving part to your setup. The package manifest shows the shape of the distribution. The bin entry maps the workers-mcp command to dist/cli.js, the main and module entries point at dist/index.js with type declarations alongside, and the files array ships only dist and the README. The build uses tsup to produce ESM output with declaration files, and there is a postbuild step that makes the emitted scripts executable. The dependency on photon-node explains the image handling in the second example, and the engines field asks for Node 16.17.0 or newer.

## Four setup steps and a restart rule you have to remember

The setup flow is short. You generate a new Worker with create-cloudflare, and the readme suggests choosing a Hello World worker. Then you move into the project directory, which the readme flags with a wry note that the author always forgets this bit, and install the package with npm install workers-mcp. Then you run the setup command, and the readme says that if something goes wrong you run npx workers-mcp help:

```shell
npx create-cloudflare@latest my-new-worker
cd my-new-worker # I always forget this bit
npm install workers-mcp
npx workers-mcp setup
```

The iteration rule afterwards is the part that catches people out. After changing your Worker code you only need to run npm run deploy to update both Claude's metadata about your function and your live Worker instance. However, if you change the names of your methods, or their parameters, or add or remove methods, Claude will not see the updates until you restart it. The readme also says you should never need to rerun npx workers-mcp install:claude, but that it is safe to do so if you want to rule out Claude config as a source of errors. So there is a split in the update path, a redeploy for code changes and a client restart for interface changes, and knowing which one you need is the difference between a tool that appears to have lost a method and one that has not been told yet.

## Client configuration differs between Cursor and everyone else

The configuration format is where the friction with other clients appears. The readme gives a standard MCP config shape with a command, an args array and an env object, and the args are a run subcommand, the server name, the workers.dev URL and the project path. For Windsurf and other MCP clients, you update the configuration file to include your worker so you could use the tools directly from the client, and the readme says to replace the placeholders with your actual server name, URL and project path. Cursor is the exception, and the reason is worth knowing. To get your Cloudflare MCP server working in Cursor you need to combine the command and args from your config file into a single string and use type command:

```json
{
  "mcpServers": {
    "your-mcp-server-name": {
      "command": "/path/to/workers-mcp",
      "args": [
        "run",
        "your-mcp-server-name",
        "https://your-server-url.workers.dev",
        "/path/to/your/project"
      ],
      "env": {}
    }
  }
}
```

Cursor wants type command and a single command string of the form path to workers-mcp run, then the server name, the URL and the project path, while the other clients take the args array as separate elements. The config therefore has to be rewritten depending on the client, and the URL is what actually determines which Worker is called.

## The examples show the intended use and the unfinished parts

The examples directory holds two examples, and they are more informative than the prose. The 01-hello-world example is described as a snapshot taken after the installation instructions above, so it is a reference for the finished state of a project rather than a separate program. The 02-image-generation example uses Workers AI to run the Flux image generation model, and the readme makes a point about why that pairing works: Claude is really good at suggesting prompts and can actually interpret the outcome and decide what new prompts to try to achieve the outcome you want. That is the shape of the intended use, a Worker holding a capability that is awkward to run locally and an agent that benefits from calling it. The remaining entries in the list are not written yet. The readme lists a TODO for Browser Rendering and a TODO for Durable Objects, both of which are the kind of stateful or browser-side capability that would benefit most from the pattern. Reading those TODOs is a fair signal of where the project stopped. The project is licensed Apache-2.0, authored by Cloudflare, and published on npm as workers-mcp.

## Conclusion

workers-mcp is worth using if you already have a Worker and want a specific function of it callable from a coding agent, since the build step reads your method signatures and the proxy handles the transport. It is the wrong choice for a new project, because the project's own warning says to start with a remote MCP server instead, and the local proxy route adds a Node process on your workstation plus a build step per method change. Verify first that the method names and parameters you expose are the ones you want in the agent's tool list, that restarting the client after a method rename is part of your workflow, and that the worker URL and project path in the client configuration point at the deployment you actually mean. The last push was on 2026-04-23 and the repository publishes no GitHub releases.

## FAQ

### What does workers-mcp do?

It provides the CLI tooling and the in-Worker logic to connect Claude Desktop or any MCP client to a Cloudflare Worker on your account. A build step translates the TypeScript methods of your Worker class into MCP tools, and a local Node.js server proxies stdio transport to the live Worker.

### How do I set up workers-mcp for a new Worker?

Generate a worker with npx create-cloudflare@latest my-new-worker, change into that directory, run npm install workers-mcp, then run npx workers-mcp setup. If something goes wrong, the readme points to npx workers-mcp help.

### Do I need to restart Claude after changing a Worker method?

Yes, if you change the names of your methods, or their parameters, or add or remove methods, Claude will not see the updates until you restart it. For code changes without an interface change, running npm run deploy is enough.

### How is the workers-mcp config different in Cursor?

Cursor needs the command and args combined into a single string and the type set to command, for example /path/to/workers-mcp run with the server name, the URL and the project path. Other clients such as Windsurf take the same values as a separate args array.

### Should I use workers-mcp or a remote MCP server?

The project itself warns that you should start with the remote MCP server guide instead, and that remote servers can be connected from Claude Desktop, Cursor and other clients using mcp-remote. The local proxy is the older path, useful when you want a specific Worker function callable without standing up a server.

## Sources

- [cloudflare/workers-mcp on GitHub](https://github.com/cloudflare/workers-mcp)
- [Issues](https://github.com/cloudflare/workers-mcp/issues)
- [License: Apache-2.0](https://github.com/cloudflare/workers-mcp/blob/main/LICENSE)
- [Project website](https://www.npmjs.com/package/workers-mcp)
- [README](https://github.com/cloudflare/workers-mcp/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cloudflare-workers-mcp