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?
The annual license includes every format and monthly data releases.
Get the complete lists Inspect sample dataWorker 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?
Put the full dataset in your stack
€99/year gets you all 22 data categories, unlimited local queries, and one year of updates. Load the files once, keep your decision logic in-house, and update on your own deployment schedule.