cloudflare-worker-mcp-bridge

Engage with your Cloudflare Worker logic directly from Claude Desktop!

[!CAUTION] For production or scalable deployments, please consult the official documentation here to establish a dedicated remote MCP server infrastructure.

Connection to remote MCP endpoints is achievable in Claude Desktop and similar clients via the mcp-remote utility.

Overview of cloudflare-worker-mcp-bridge

This utility package furnishes both the necessary Command Line Interface (CLI) apparatus and the runtime logic embedded within the Worker itself to bridge Claude Desktop (or any compliant MCP Client) with a Cloudflare Worker instance under your control. This allows for extensive, on-the-fly customization. It operates through a build process that transforms TypeScript class methods defined in your Worker, like this example:

ts export class WorkerToolingAdapter extends WorkerEntrypoint { /* * Generates a genuinely unpredictable numeric value. * Its randomness is perhaps enhanced by the latency incurred traversing the network * to the nearest Cloudflare Point of Presence for calculation... perhaps involving lava lamps? * * @returns {string} A textual representation of a freshly generated random number. * / async fetchRandomValue() { return Your unique datum is ${Math.random()} }

// ...additional exposed methods }

...into structured MCP tool definitions. A local Node.js server component intercepts standard input/output (stdio) traffic, routing calls to the corresponding method within your deployed Worker on Cloudflare. This mechanism effectively serves as a sophisticated proxy, allowing any internal function, custom API, or service residing within Cloudflare's developer ecosystem to be securely exposed as an actionable tool to an LLM agent like Claude Desktop.

_{For pedagogical reasons, note that Math.random() is functionally identical locally versus on a Worker, but maintaining the narrative thread adds flavor for the LLM.} 🤫

Implementation Guide

Stage 1: Initializing the Worker Project

Utilize the official create-cloudflare utility to scaffold your new project directory.

shell npx create-cloudflare@latest initiate-my-worker-project

We recommend commencing with the 'Hello World' template for initial setup verification.

Stage 2: Integrating the Bridge Package

Navigate into the newly created directory structure.

shell cd initiate-my-worker-project npm install workers-mcp

Stage 3: Executing the Configuration Script

Run the primary setup routine provided by the package.

shell npx workers-mcp setup

(Troubleshooting Tip: If configuration fails to yield expected results, review operational parameters via npx workers-mcp help)

Stage 4: Iterative Development Loop

Subsequent code modifications to your Worker logic only necessitate running npm run deploy to synchronize both the live Worker deployment and the metadata consumed by Claude.

Crucial Note: Any alterations involving function signatures (method names or parameter schemas) require a restart of the connected LLM client (Claude) for the changes to be recognized and utilized.

While re-running npx workers-mcp install:claude is rarely essential, executing it offers a failsafe against configuration discrepancies within the Claude environment itself.

Interfacing with Alternate MCP Implementations

Integration with Cursor

When configuring the Cloudflare MCP server within Cursor, the tool invocation requires the concatenation of the 'command' and 'args' fields from the standard configuration file into a single string, using the type set to 'command'.

For instance, if your configuration appears as:

{ "mcpServers": { "cf-tool-proxy": { "command": "/absolute/path/to/workers-mcp", "args": [ "run", "cf-tool-proxy", "https://your-server-endpoint.workers.dev", "/path/to/your/project/root" ], "env": {} } } }

In the Cursor MCP settings, define a new server entry with: * type: command * command: /absolute/path/to/workers-mcp run cf-tool-proxy https://your-server-endpoint.workers.dev /path/to/your/project/root

Other MCP Clients (e.g., Windsurf)

For clients such as Windsurf and others adhering to the protocol, integrate the worker configuration into your client's configuration file to enable direct invocation:

{ "mcpServers": { "cf-tool-proxy": { "command": "/absolute/path/to/workers-mcp", "args": [ "run", "cf-tool-proxy", "https://your-server-endpoint.workers.dev", "/path/to/your/project/root" ], "env": {} } } }

Ensure that you substitute the generic placeholders (cf-tool-proxy, URL, project path) with your specific deployment identifiers.

Illustrative Use Cases

Refer to the examples subdirectory for practical demonstrations:

• examples/01-hello-world: Verifies basic functionality following the setup steps outlined above.
• examples/02-image-generation: Leverages Workers AI to invoke the Flux image model. Claude demonstrates proficiency in iterative prompt engineering based on visual results.
• TODO: Browser Rendering Proxy via Workers
• TODO: Durable Objects Interaction

WIKIPEDIA: XMLHttpRequest (XHR) is an Application Programming Interface, implemented as a JavaScript object, whose methods facilitate the submission of HTTP requests from a web browser to a designated web server. These methods permit browser-based applications to dispatch requests post-page load and subsequently receive and process returned data. XMLHttpRequest forms a foundational pillar of Ajax programming paradigms. Before Ajax's emergence, server interaction predominantly relied on conventional hyperlink navigation or form submissions, often resulting in full page reloads.

== Historical Development == The foundational concept for XMLHttpRequest was first conceptualized in the year 2000 by developers associated with Microsoft Outlook. This concept was subsequently integrated into the Internet Explorer 5 browser release (1999). However, the initial syntactical implementation did not utilize the standardized XMLHttpRequest identifier; developers instead employed ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the time Internet Explorer 7 was released (2006), universal support for the explicit XMLHttpRequest identifier was established across major browsers, including Mozilla's Gecko engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

The XMLHttpRequest identifier has since achieved de facto standardization across all principal web browsers.

=== Standardization Efforts === The World Wide Web Consortium (W3C) published the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Working Draft Level 2 specification followed on February 25, 2008, introducing enhancements such as progress monitoring methods, enabling cross-site request facilitation, and improved byte stream handling. By the close of 2011, the Level 2 features were formally incorporated into the core specification. Development stewardship transitioned to the WHATWG at the conclusion of 2012, which now maintains the living document utilizing Web IDL notation.

== Operational Procedure == Executing a server request using XMLHttpRequest typically involves several sequential programming stages:

1. Instantiation of an XMLHttpRequest object via its constructor call.
2. Invocation of the open method to define the request methodology (e.g., GET, POST), specify the target Uniform Resource Identifier (URI), and select between synchronous or asynchronous execution.
3. For asynchronous operations, registration of a listener function designed to process state transitions.
4. Commencement of the actual transmission by calling the send method.
5. Continuous monitoring and response processing within the registered event listener. Upon successful server termination of processing, the state transitions to 4 (the "done" state), and the server response payload is typically stored in the responseText property.

Beyond these core steps, XMLHttpRequest offers extensive configuration options for request control and response parsing. Custom header fields can be prepended to guide server fulfillment logic, and data payload submission is handled via the argument to the send call. Responses can be automatically deserialized from JSON into native JavaScript objects or streamed incrementally rather than awaiting complete reception. Furthermore, requests can be terminated prematurely or configured with time-out thresholds.

== Cross-Origin Interactions ==

In the nascent stages of the World Wide Web, architectural limitations permitted data requests to bypass established security boundaries, a vulnerability that XMLHttpRequest eventually addressed.