# cloudflare/workers-mcp architecture

> Architecture diagram of the GitHub repository cloudflare/workers-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cloudflare/workers-mcp
- Repository: https://github.com/cloudflare/workers-mcp

## Overview

##### Project Overview
- Purpose: The project provides CLI tooling and in-Worker logic to let a local MCP client (like Claude Desktop, Cursor, or Windsurf) connect to a Cloudflare Worker. In this architecture, the tool translates TypeScript methods from your Worker into MCP-accessible functions via a local Node.js proxy.
- Type: It’s an integration and proxy tool bridging a Cloudflare Worker environment with local MCP clients.

##### Key Components
a. Local Node.js Environment (CLI/Proxy Server):
- Entry Points: The main files such as src/cli.ts and src/index.ts indicate that this project exposes a CLI and a primary execution script.
- Proxy Modules: The modules directory contains Proxy.ts, ProxyToDO.ts, and ProxyToSelf.ts. These modules are responsible for handling different types of proxying:
- Proxy.ts: Likely the common or abstract proxy logic.
- ProxyToDO.ts: Possibly handles proxy requests that involve Cloudflare Durable Objects.
- ProxyToSelf.ts: Might handle proxied calls that loop back to the local service.
- Utility Scripts: Under the src/scripts folder are several scripts for tasks like documentation generation, local-proxy handling, installation, and setup, which are all important for the build/deployment process.

b. Cloudflare Worker:
- While the Worker’s actual code might not live entirely in this repository, the README demonstrates how your Worker should implement methods (via the WorkerEntrypoint class) that are processed by workers-mcp.
- This Worker is deployed on Cloudflare and will run your business logic when called.

c. External MCP Clients:
- Clients like Claude Desktop, Cursor and others are external applications that connect to the local proxy. They initiate commands that the proxy translates into method calls on the Worker.
- The README shows that the MCP client’s configuration (with command and args) is a key piece in the integration.

##### Relationships and Data Flow
- MCP Client Initiation:
- MCP clients send requests which enter the system via the local CLI (or a Node.js server started by it).
- Local Proxied Processing:
- The CLI/proxy server (using modules like Proxy, ProxyToDO, ProxyToSelf) receives these requests.
- It translates and dispatches calls by connecting to the Cloudflare Worker instance (deployed on Cloudflare PoPs).
- Cloudflare Worker Execution:
- The Cloudflare Worker (guided by code conforming to WorkerEntrypoint) receives and processes the request, executing the desired business logic (e.g., returning random numbers, invoking image generation, etc.).
- The Worker’s response is then passed back through the same proxy chain to the MCP client.

##### Architectural Patterns and Technologies
- Separation of Concerns: There’s a clear separation between CLI commands, proxy logic, and the Worker logic.
- Proxy Pattern: Using dedicated Proxy modules to route and transform requests.
- Build/Deployment Integration: The project supports code generation steps (see the scripts like generate-docs.ts and setup.ts) that integrate build and deployment phases.
- TypeScript & Node.js: The entire toolchain is built with TypeScript, ensuring type safety for both local processing and worker integration.
- Cloudflare Platform: The architecture depends on Cloudflare Workers, with configuration files (e.g., wrangler.toml in the examples) indicating deployment specifics.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    MCPClients["MCP Client(s)"]:::external

    %% Local CLI/Proxy Server Subgraph
    subgraph "Local Proxy/CLI Server"
        %% CLI Entry Points Subgroup
        subgraph "CLI Entry Points"
            CLI1["CLI Entry: src/cli.ts"]:::local
            CLI2["CLI Entry: src/index.ts"]:::local
        end
        %% Proxy Modules Subgroup
        subgraph "Proxy Modules"
            Proxy["Proxy Module: Proxy.ts"]:::local
            ProxyDO["Proxy Module: ProxyToDO.ts"]:::local
            ProxySelf["Proxy Module: ProxyToSelf.ts"]:::local
        end
        Utility["Utility & Build Scripts: src/scripts"]:::local
    end

    %% Cloudflare Worker Subgraph
    subgraph "Cloudflare Worker"
        Worker["Worker: Cloudflare Environment"]:::cloud
        subgraph "Worker Examples"
            Example1["Worker Example: 01-hello-world"]:::cloud
            Example2["Worker Example: 02-image-generation"]:::cloud
        end
    end

    %% Data Flow connections
    MCPClients -->|"initiateRequest"| CLI1
    MCPClients -->|"initiateRequest"| CLI2

    CLI1 -->|"dispatch"| Proxy
    CLI2 -->|"dispatch"| Proxy
    Proxy -->|"forwardRequest"| Worker
    ProxyDO -->|"handleDO"| Worker
    ProxySelf -->|"handleSelfCall"| Worker

    Worker -->|"responseReturn"| Proxy
    Proxy -->|"relayResponse"| CLI1
    Proxy -->|"relayResponse"| CLI2
    CLI1 -->|"sendBackResponse"| MCPClients
    CLI2 -->|"sendBackResponse"| MCPClients

    %% Utility scripts influence (dashed connection) to CLI and Proxy modules for build/deployment
    Utility ---|"buildDocs/setup"| CLI1
    Utility ---|"buildDocs/setup"| Proxy

    %% Worker sub-components
    Worker -->|"implements"| Example1
    Worker -->|"implements"| Example2

    %% Click Events for Local CLI/Proxy Server Entry Points
    click CLI1 "https://github.com/cloudflare/workers-mcp/blob/main/src/cli.ts"
    click CLI2 "https://github.com/cloudflare/workers-mcp/blob/main/src/index.ts"

    %% Click Events for Proxy Modules
    click Proxy "https://github.com/cloudflare/workers-mcp/blob/main/src/modules/Proxy.ts"
    click ProxyDO "https://github.com/cloudflare/workers-mcp/blob/main/src/modules/ProxyToDO.ts"
    click ProxySelf "https://github.com/cloudflare/workers-mcp/blob/main/src/modules/ProxyToSelf.ts"

    %% Click Event for Utility Scripts Folder
    click Utility "https://github.com/cloudflare/workers-mcp/tree/main/src/scripts"

    %% Click Events for Cloudflare Worker Examples
    click Example1 "https://github.com/cloudflare/workers-mcp/blob/main/examples/01-hello-world/src/index.ts"
    click Example2 "https://github.com/cloudflare/workers-mcp/blob/main/examples/02-image-generation/src/index.ts"

    %% Class Definitions for Colors
    classDef external fill:#FFECB3,stroke:#F57C00,stroke-width:2px;
    classDef local fill:#BBDEFB,stroke:#1976D2,stroke-width:2px;
    classDef cloud fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
```
