worker-mcp

A high-performance MCP (Model Context Protocol) server running on Cloudflare Workers/Pages edge computing platforms.

Features

• Web Dashboard - Visual interface to browse and test MCP tools
• MCP Protocol - Full JSON-RPC 2.0 support over HTTP/SSE
• Built-in Tools:
  • add - Simple addition calculator
  • searxng_web_search - Web search via SearXNG
  • web_url_read - Fetch and read URL content
  • sequentialthinking - Structured problem-solving tool

Getting Started

Install Dependencies

npm install

Local Development

# Cloudflare Workers (recommended)
npm run dev

# Or Cloudflare Pages
npm run dev:pages

Open http://localhost:8787 in your browser to see the dashboard.

Connect MCP Inspector

Use MCP Inspector to test your server:

npx @modelcontextprotocol/inspector

Configure the inspector:

• Transport Type: SSE
• URL: http://localhost:8787/mcp

<!-- SCREENSHOT PLACEHOLDER: MCP Inspector connection config Capture: Inspector with SSE transport selected and URL field filled Location: MCP Inspector "Configure" tab Replace: mcp-inspector-config.png -->

After connecting, you should see your available tools and be able to call them.

Connect to Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "worker-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8787/mcp"]
    }
  }
}

Deployment

Cloudflare Workers (Recommended)

npm run deploy

Cloudflare Pages

npm run deploy:pages

Environment Variables

Variable	Required	Description
API_KEY	No	API key for MCP endpoint authentication

Project Structure

worker-mcp/
├── src/
│   ├── index.ts        # Workers entry point
│   ├── app.ts          # Hono web app (dashboard)
│   ├── server.ts       # MCP request handler
│   └── tools/          # MCP tool implementations
│       ├── index.ts
│       ├── add.ts
│       ├── web-search.ts
│       ├── web-url-read.ts
│       └── sequentialthinking.ts
├── pages/
│   ├── _worker.ts      # Pages Functions entry point
│   └── _routes.json    # Pages routing config
├── static/             # Static assets (dashboard UI)
├── wrangler.jsonc      # Workers configuration
├── package.json
└── biome.json          # Code formatting/linting

API Endpoint

Endpoint	Method	Description
/	GET	Web dashboard
/mcp	POST	MCP JSON-RPC 2.0 endpoint

MCP Endpoint

URL: https://your-worker.workers.dev/mcp

Authentication (if API_KEY is set):

# Via header
curl -H "Authorization: Bearer YOUR_API_KEY" https://your-worker.workers.dev/mcp

# Or via query parameter
curl https://your-worker.workers.dev/mcp?apiKey=YOUR_API_KEY

Troubleshooting

Clear MCP auth cache

rm -rf ~/.mcp-auth

Check logs

npx wrangler tail

License

MIT