Cloudflare Worker MCP Server

A Model Context Protocol (MCP) server deployed on Cloudflare Workers with Durable Objects, exposing a suite of web-search and web-fetch tools over the Streamable HTTP transport.

Live endpoint: https://your-worker.workers.dev/mcp

---

Tools

Tool	Description
web_search	Neural web search via Exa AI — returns titles, URLs, dates, and highlights
web_fetch_html	Fetch a URL and return raw HTML
web_fetch_markdown	Fetch a URL via Exa /contents and return clean extracted text
web_fetch_json	Fetch one or more URLs via Exa /contents and return structured JSON
web_fetch_txt	Fetch a URL and return plain text (strips HTML tags)
web_github_search	Search code across public GitHub repos via grep.app
web_github_readme	Fetch any file (default: README.md) from a public GitHub repo
web_search_engine	Search via alternative engines: bing, baidu, juejin, startpage
web_google_search	Google search grounded answer via Gemini API with inline citations

---

Requirements

• Node.js 18+
• Wrangler CLI (npm i -g wrangler)
• A Cloudflare account (free tier works)
• An Exa API key (free tier available)
• A Gemini API key (free tier available)

---

Setup

1. Clone and install

git clone https://github.com/hypnguyen1209/cf-worker-mcp.git
cd cf-worker-mcp
npm install

2. Configure

Copy the example config and fill in your API keys:

cp wrangler.example.jsonc wrangler.jsonc

Edit wrangler.jsonc:

{
  "name": "mcp",                          // your worker name → <name>.workers.dev
  "vars": {
    "EXA_API_KEY": "your-exa-key",
    "GEMINI_API_KEY": "your-gemini-key",
    "GEMINI_MODEL": "gemini-2.5-flash"
  }
}

Alternatively, store secrets securely with Wrangler (recommended for production):

npx wrangler secret put EXA_API_KEY
npx wrangler secret put GEMINI_API_KEY

3. Generate types

npm run cf-typegen

4. Run locally

npm run dev
# MCP endpoint: http://localhost:8787/mcp

5. Deploy

npm run deploy
# MCP endpoint: https://<name>.workers.dev/mcp

---

Usage with MCP clients

Add to your MCP client config (e.g. Claude Desktop, Cursor, VS Code Copilot):

{
  "mcpServers": {
    "web": {
      "type": "http",
      "url": "https://your-worker.workers.dev/mcp"
    }
  }
}

The server also supports the legacy SSE transport at /sse for older clients.

---

Health check

GET / returns a JSON discovery document:

{
  "name": "mcp-worker",
  "version": "1.0.0",
  "endpoint": "https://your-worker.workers.dev/mcp",
  "tools": ["web_search", "web_fetch_html", "..."]
}

---

Project structure

src/
  index.ts          # All tools + Worker fetch handler
wrangler.jsonc      # Your config with API keys (gitignored)
wrangler.example.jsonc  # Template to commit
test-tools.mjs      # End-to-end smoke test (node test-tools.mjs)

---

License

MIT