English | 中文

An aggregated search API service based on Cloudflare Workers

Supports MCP (Model Context Protocol), giving AI assistants (OpenClaw, Claude Code, Codex, OpenCode) real-time web search capabilities

• 🔍 Multi-engine Aggregation - Use multiple search engines at the same time (Google, Brave, DuckDuckGo, Bing)
• 🤖 AI Enhanced (MCP) - Native support for Model Context Protocol, one-click search tool integration for OpenClaw / Claude Code / Codex
• ⚡ Parallel Search - All search engines are requested concurrently for faster results
• 🛡️ Fault Tolerance - Failure of a single engine does not affect others; unresponsive engines are automatically marked
• ⏱️ Timeout Control - Configurable request timeout to avoid long waits
• 🔒 Token Authentication - Supports token auth to protect the service from abuse
• 🌍 CORS Support - Full cross-origin resource sharing support
• 🎨 Web Interface - Provides a clean search UI for easy testing
• ⚡ Zero-cost Operation - Cloudflare Workers free tier supports 100,000 requests per day

With MCP (Model Context Protocol), AI assistants can directly call your search service and get real-time search results.

First, follow the guide to Deploy Cloudflare Search

Edit your config file (configuration guide):

• OpenClaw: ~/.openclaw/openclaw.json
• Claude Code: ~/.claude/config.json / ~/.claude.json
• Claude Desktop macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop Windows: %APPDATA%\Claude\claude_desktop_config.json

{
	"mcpServers": {
		"cloudflare-search": {
			"command": "npx",
			"args": ["-y", "@yrobot/cf-search-mcp"],
			"env": {
				"CF_SEARCH_URL": "https://your-worker.workers.dev",
				"CF_SEARCH_TOKEN": "your-token-here"
			}
		}
	}
}

Environment Variables:

• CF_SEARCH_URL: Worker deployment URL (required)
• CF_SEARCH_TOKEN: Auth token (required if your Worker has TOKEN configured)

• OpenClaw: Run openclaw gateway restart + openclaw mcp list and check that cloudflare-search appears
• Claude Code:
  • Run /mcp in Claude Code, and you should see the cloudflare-search tool.
  • Or run claude mcp list; seeing cloudflare-search: npx -y @yrobot/cf-search-mcp@latest - ✓ Connected means setup is successful

Click the "Deploy to Cloudflare Workers" button above and follow the prompts.

# 1. Install Wrangler
npm install -g wrangler

# 2. Login to Cloudflare
wrangler login

# 3. Clone the repository
git clone https://github.com/Yrobot/cloudflare-search.git
cd cloudflare-search

# 4. Deploy
wrangler deploy

1. Sign in to Cloudflare Dashboard
2. Go to Workers & Pages
3. Click Create Application > Create Worker
4. Click Upload to upload your local code folder
   • Select the cloned cloudflare-search folder
   • Or manually copy worker.js, envs.js, utils/, and other files
5. Click Save and Deploy

After deployment, you will get a Worker URL:

https://your-worker-name.your-subdomain.workers.dev

Note: The default domain may not be directly accessible in some regions. It is recommended to bind your own custom domain.

Open your Worker URL directly and enter search keywords in the web UI:

https://$YOUR-DOMAIN/

Search using query parameters:

# Basic search
curl "https://$YOUR-DOMAIN/search?q=cloudflare"

# Specify search engines
curl "https://$YOUR-DOMAIN/search?q=cloudflare&engines=google,brave"

# Use token authentication (if TOKEN env var is configured)
curl "https://$YOUR-DOMAIN/search?q=cloudflare&token=$YOUR-TOKEN"

Submit search by POST form:

curl -X POST "https://$YOUR-DOMAIN/search" \
	-d "q=cloudflare" \
	-d "engines=google,brave"
	-d "token=$YOUR-TOKEN" # if TOKEN env var is configured

Used to execute search queries and return aggregated results.

Supported Search Engines:

• google - Google Search (requires API Key configuration)
• brave - Brave Search
• duckduckgo - DuckDuckGo Search
• bing - Bing Search

{
	query: string;                    // Search keyword
	number_of_results: number;        // Total number of results
	enabled_engines: string[];        // Enabled search engine list
	unresponsive_engines: string[];   // Unresponsive search engine list
	results: Array<{
		title: string;                  // Result title
		description: string;            // Result description
		url: string;                    // Result link
		engine: string;                 // Source engine
	}>;
}

# GET request
curl "https://$YOUR-DOMAIN/search?q=cloudflare&engines=google,brave"

# POST request
curl -X POST "https://$YOUR-DOMAIN/search" \
	-H "Content-Type: application/x-www-form-urlencoded" \
	-d "q=cloudflare&engines=google,brave"

{
	"query": "cloudflare",
	"number_of_results": 15,
	"enabled_engines": ["google", "brave", "duckduckgo"],
	"unresponsive_engines": [],
	"results": [
		{
			"title": "Cloudflare - The Web Performance & Security Company",
			"description": "Cloudflare is on a mission to help build a better Internet...",
			"url": "https://www.cloudflare.com/",
			"engine": "google"
		},
		{
			"title": "Cloudflare Workers",
			"description": "Deploy serverless code instantly across the globe...",
			"url": "https://workers.cloudflare.com/",
			"engine": "brave"
		}
	]
}

1. Parallel Requests: All enabled search engines are requested concurrently to improve response speed
2. Timeout Control: Timeout of a single engine does not affect others; default timeout is 3 seconds
3. Result Aggregation: Merge all successfully returned results and mark their source engine
4. Fault Tolerance: Record unresponsive engines and return partial results instead of failing completely

Notes:

• Google Custom Search API free tier is limited to 100 requests per day
• After TOKEN is configured, all requests must provide a valid token

Edit the [vars] section in wrangler.toml:

[vars]
GOOGLE_API_KEY = "your-google-api-key"
GOOGLE_CX = "your-google-custom-search-cx"
DEFAULT_TIMEOUT = "3000"
TOKEN = "your-secret-token-here"

1. Go to the Worker settings page
2. Find the Environment Variables section
3. Add variables and save

Build your own aggregated search API and combine results from multiple search engines:

const response = await fetch(
	"https://$YOUR-DOMAIN/search?q=javascript&engines=google,brave",
);
const data = await response.json();
console.log(`Found ${data.number_of_results} results`);

Add search functionality to your website or app:

async function search(query) {
	const response = await fetch(
		`https://$YOUR-DOMAIN/search?q=${encodeURIComponent(query)}`,
	);
	const data = await response.json();
	return data.results;
}

Collect results from multiple search engines for comparative analysis:

const engines = ["google", "brave", "duckduckgo"];
const results = await fetch(
	`https://$YOUR-DOMAIN/search?q=AI&engines=${engines.join(",")}`,
);
const data = await results.json();

// Group by engine
const byEngine = data.results.reduce((acc, result) => {
	acc[result.engine] = acc[result.engine] || [];
	acc[result.engine].push(result);
	return acc;
}, {});

With MCP (Model Context Protocol), AI assistants can directly call your search service and get real-time search results.

1. Use a Custom Domain

   • The default Cloudflare *.workers.dev domain may be inaccessible in some regions
   • It is strongly recommended to bind your own domain for a better access experience
   • In Worker settings, click Triggers > Add Custom Domain to add a custom domain

2. Search Engine Limits

   • Google API free tier is limited to 100 requests per day
   • Other search engines generally do not have strict limits, but please use responsibly
   • Frequent requests may cause temporary rate limiting

3. Timeout Settings

   • Default timeout per engine is 3 seconds
   • Can be adjusted with DEFAULT_TIMEOUT
   • Do not set it too high to avoid long overall response times

1. Configure the TOKEN environment variable to protect your service from abuse:

• Configure TOKEN in wrangler.toml
• Configure TOKEN in Cloudflare Worker Dashboard

2. Pass token in requests:

# Access homepage
https://$YOUR-DOMAIN?token=$YOUR-TOKEN

# Request API with token parameter in query/body
curl "https://$YOUR-DOMAIN/search?q=cloudflare&token=$YOUR-TOKEN"

curl -X POST "https://$YOUR-DOMAIN/search" \
	-d "q=cloudflare" \
	-d "token=$YOUR-TOKEN"

A: Possible reasons:

• Search engine API is temporarily unavailable or timed out
• No relevant results for the search keyword
• Search engine has rate-limited access
• Google requires API Key configuration before use

You can check the unresponsive_engines field in the response to see which engines did not respond.

A: Recommendations:

• Reduce the number of enabled search engines and only use the engines you need
• Adjust timeout (DEFAULT_TIMEOUT) appropriately

A: Bing search results are currently not stable enough, and may return content with low relevance to the query. If needed, you can manually specify engines=bing in requests or modify DEFAULT_ENGINES in envs.js.

A: It is recommended to configure the TOKEN environment variable to enable authentication:

1. Set TOKEN = "your-random-token" in wrangler.toml
2. Or add it in Environment Variables in Cloudflare Dashboard
3. After configuration, all requests must provide a valid token

Authentication failure returns a 401 error.

This project is for learning and research purposes only. Users must comply with the following:

1. Lawful Use - Only use for legal search purposes. Do not use for illegal or infringing activities
2. Terms of Service - Comply with the terms of Cloudflare Workers and each search engine
3. API Limits - Follow usage limits and quotas of each search engine API
4. Use at Your Own Risk - Any consequences from using this service are the user's responsibility
5. Commercial Use - For commercial use, ensure compliance with relevant laws, regulations, and service terms

Issues and Pull Requests are welcome!

GPL-3 License

• Project GitHub
• Cloudflare Workers Docs
• Google Custom Search API

If this project helps you, you can buy the author a coffee ☕