Cloud / CDN
Cloudflare Workers Blocklist Tutorial
Block VPN and proxy IPs at the Cloudflare edge using Workers KV to store the blocklist and a Worker script to intercept requests before they reach your origin.
Steps
- 1
Create a Workers KV namespace
In the Cloudflare dashboard (or via Wrangler CLI) create a KV namespace named BLOCKLIST to store the IP set.
- 2
Upload blocklist to KV
Use a Node.js script or the Cloudflare API to populate KV with the blocklist IPs as keys (value = "1").
- 3
Write the Worker script
The Worker reads the client IP from the CF-Connecting-IP header, checks it against KV, and returns 403 if found.
- 4
Deploy the Worker
Deploy with wrangler deploy. The Worker runs at all Cloudflare edge locations globally.
Need the blocklist files?
Download free sample data or subscribe for daily-updated lists.
Free SampleWorker script
Edge Worker that checks the connecting IP against KV blocklist.
export interface Env {
BLOCKLIST: KVNamespace;
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const clientIP =
request.headers.get('CF-Connecting-IP') ??
request.headers.get('X-Real-IP') ??
'0.0.0.0';
// Check if IP is in the blocklist KV namespace
const blocked = await env.BLOCKLIST.get(clientIP);
if (blocked !== null) {
return new Response('Access denied', { status: 403 });
}
// Pass through to origin
return fetch(request);
},
};wrangler.toml
Wrangler config binding the KV namespace to the Worker.
name = "antiproxies-blocker"
main = "src/index.ts"
compatibility_date = "2025-01-01"
[[kv_namespaces]]
binding = "BLOCKLIST"
id = "YOUR_KV_NAMESPACE_ID"Frequently asked questions
Are Workers KV reads fast enough to not add latency?
How much does Workers KV cost for a large blocklist?
Can I also block by country at the edge?
Want to see what's in the database?
Download once, query as many times as you need. €99/year for all 22 databases, unlimited servers, and a full year of monthly updates. No usage limits, no per-query fees, no data leaving your servers.