Cloudflare MCP Server
💡 Note: This project was entirely generated using AI coding assistants under my direction. I designed the architecture, defined the tools, shaped the API logic, and iteratively refined the system with prompt engineering. The goal of this project is to explore what's possible when AI is treated as a full-stack development partner. No manual coding was done — but every component (structure, logic, docs, safety notes, examples) was guided, validated, and produced through my prompts.
A Model Context Protocol (MCP) server that provides both tools and resources for Cloudflare Ruleset Engine API management and documentation access.
Features
Tools
- Zone Management: List zones, get zone details
- Account Management: List accounts accessible to the authenticated user
- Device Certificate Provisioning: Enable/disable client certificate provisioning for WARP Device Information Only mode
- Rulesets Management:
- List rulesets for zones or accounts
- Get ruleset details
- Add rules to rulesets
- Update existing rules
- Delete rules from rulesets
- List ruleset versions
- Get specific ruleset version
- Get ruleset version filtered by tag
- Documentation Access: List and read Cloudflare documentation files
Resources
- Documentation Access: Access to all Cloudflare documentation in the
ruleset-enginefolder via MCP resources - Resource Templates: Dynamic access to documentation via URI templates (
cloudflare://docs/{relative_path}) - Documentation Catalog: List and filter documentation resources by category
Installation
Prerequisites
- Python 3.10+ (3.11 recommended)
- pip
Quick Start
- Clone the repository:
git clone https://github.com/quareth/cloudflare_waf_mcp.git
cd cloudflare_waf_mcp
- (Recommended) Create and activate a virtual environment:
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
- Install dependencies:
pip install --upgrade pip
pip install -r requirements.txt
- Configure credentials (choose one method):
Option A: MCP Client Configuration (Recommended for MCP clients) If you're using an MCP client (like Claude Desktop or Cursor), you can configure the API key directly in the client's configuration file.
Using Virtual Environment (Recommended):
Windows:
{
"mcpServers": {
"cloudflare": {
"command": "C:\\path\\to\\cloudflare_waf_mcp\\venv\\Scripts\\python.exe",
"args": ["-m", "src.cloudflare_waf_mcp_server.server"],
"env": {
"CLOUDFLARE_API_TOKEN": "your_cloudflare_api_token_here",
"PYTHONPATH": "C:\\path\\to\\cloudflare_waf_mcp"
}
}
}
}
Linux/Mac:
{
"mcpServers": {
"cloudflare": {
"command": "/path/to/cloudflare_waf_mcp/venv/bin/python",
"args": ["-m", "src.cloudflare_waf_mcp_server.server"],
"env": {
"CLOUDFLARE_API_TOKEN": "your_cloudflare_api_token_here",
"PYTHONPATH": "/path/to/cloudflare_waf_mcp"
}
}
}
}
Using System Python (if dependencies installed globally):
{
"mcpServers": {
"cloudflare": {
"command": "python",
"args": ["-m", "src.cloudflare_waf_mcp_server.server"],
"env": {
"CLOUDFLARE_API_TOKEN": "your_cloudflare_api_token_here",
"PYTHONPATH": "/path/to/cloudflare_waf_mcp"
}
}
}
}
Note: Replace the paths with your actual project directory. Use absolute paths for the venv Python executable and PYTHONPATH.
Using HTTP/SSE Transport:
⚠️ Security Warning: SSE/HTTP mode is intended for use behind a trusted network boundary (localhost, VPN, or internal network). Do not expose this server directly to the public internet without adding authentication and proper access controls.
For HTTP/SSE mode, first start the server manually, then configure the MCP client to connect via URL:
- Start the server in SSE mode:
Windows:
C:\path\to\cloudflare_waf_mcp\venv\Scripts\python.exe -m src.cloudflare_waf_mcp_server.server --sse --host 0.0.0.0 --port 8000
Linux/Mac:
/path/to/cloudflare_waf_mcp/venv/bin/python -m src.cloudflare_waf_mcp_server.server --sse --host 0.0.0.0 --port 8000
- Configure MCP client to connect via URL:
{
"mcpServers": {
"cloudflare": {
"url": "http://localhost:8000/sse",
"env": {
"CLOUDFLARE_API_TOKEN": "your_cloudflare_api_token_here"
}
}
}
}
Note: For HTTP/SSE mode, environment variables should be set when starting the server (via system env, .env file, or export commands), as the env section in MCP config may not be passed to HTTP servers.
Option B: Environment File (Recommended for standalone usage)
cp example.env .env
# Edit .env with your Cloudflare API credentials
# Required: CLOUDFLARE_API_TOKEN
Option C: System Environment Variables Set environment variables in your shell:
export CLOUDFLARE_API_TOKEN="your_token_here"
- Run the server:
Standard mode (stdio):
python -m src.cloudflare_waf_mcp_server.server
SSE/HTTP mode:
⚠️ Security Warning: SSE/HTTP mode should only be used behind a trusted network boundary. Do not expose to the public internet without authentication.
python -m src.cloudflare_waf_mcp_server.server --sse --host 0.0.0.0 --port 8000
Configuration Priority
The server reads configuration in this order (first found wins):
- MCP Client
envsection (if configured in MCP client) - System environment variables (e.g.,
export CLOUDFLARE_API_TOKEN=...) .envfile in the project root
Security Considerations
MCP Client Configuration (env section):
- ✅ Pros: Convenient, no separate
.envfile needed, works well with MCP clients - ⚠️ Cons: API key stored in client config file (usually JSON). If the config file is shared or committed, the key is exposed
Environment Variables / .env file:
- ✅ Pros: More secure, can be excluded from version control via
.gitignore - ⚠️ Cons: Requires separate configuration step
Recommendation:
- For personal/local use: MCP client
envsection is fine - For shared systems or CI/CD: Use environment variables or
.envfile (and ensure.envis in.gitignore) - Never commit API keys to version control, regardless of method
Troubleshooting
-
"ModuleNotFoundError: No module named 'fastmcp'" or similar:
- The MCP client is using a Python that doesn't have dependencies installed
- Solution: Use the venv Python path in your MCP config (see Option A above)
- Verify:
venv\Scripts\python.exe -m pip listshould showfastmcpinstalled
-
"ENOENT" or "The system cannot find the path specified":
- The venv path in MCP config is incorrect
- Solution: Check if your venv is named
venvor.venvand update the path accordingly - Windows: Verify with
Test-Path C:\path\to\project\venv\Scripts\python.exe(PowerShell) - Linux/Mac: Verify with
test -f /path/to/project/venv/bin/python && echo "exists"
-
"Resource not found": Ensure you're running from the repository root where
src/cloudflare_waf_mcp_server/ruleset-engine/exists. -
Auth errors: Verify
CLOUDFLARE_API_TOKENhas the necessary permissions (e.g., WAF/Rulesets write for rule creation). -
Documentation not found: Set
CLOUDFLARE_DOCS_ROOTenvironment variable to the absolute path ofsrc/cloudflare_waf_mcp_server/ruleset-engine.
Usage Recommendations
Multi-Zone and Multi-Account Environments
When working with multiple zones or accounts, follow these best practices:
- Always specify zone/account explicitly: For any changes or operations, clearly specify which zone or account you want to work with
- List before operations: If you have more than one zone, try to list the zones first or always specify zone names for any changes
- Use discovery tools: You can make the LLM list available zones or accounts using:
cloudflare_list_accounts()- to see all accessible accountscloudflare_list_zones()- to see all zones (optionally filtered by account)
- Be explicit: In multi-account or multi-zone environments, always clearly specify the account/zone that you will work with to avoid unintended changes
Safety Considerations
- Ruleset deletion: To prevent destructive behavior, ruleset deletion methods are not included in this MCP server. However, the server is capable of removing individual rules from rulesets using
cloudflare_delete_ruleset_rule() - Rule management: You can safely add, update, and delete individual rules within rulesets without affecting the entire ruleset structure
Resource URI Scheme
The server uses a custom URI scheme for documentation resources:
cloudflare://docs/path/to/file.md- Access specific documentation filescloudflare://docs/reference/field-name.md- Access reference documentationcloudflare://docs/examples/example-name.md- Access example documentation
MCP Resources Implementation
Based on the MCP Resources specification, this server provides:
Capabilities
resources.subscribe: Subscribe to resource changesresources.listChanged: Notifications when resource list changes
Resource Operations
resources/list: List all available documentation resourcesresources/read: Read specific documentation contentresources/templates/list: List resource templates for dynamic access
Resource Annotations
audience: ["user", "assistant"] - Content useful for bothpriority: 0.5-0.7 - Importance level (reference docs have higher priority)lastModified: ISO 8601 timestamp
Actual Implemented Features
Tools (14 total):
cloudflare_list_document_names- List documentation filescloudflare_read_document- Read documentation contentcloudflare_list_zones- List Cloudflare zonescloudflare_get_zone_details- Get zone detailscloudflare_list_accounts- List Cloudflare accountsclient_certificate_provisioning_enable- Enable/disable client certificate provisioning for Device Information Only modecloudflare_list_rulesets- List rulesetscloudflare_get_ruleset- Get ruleset detailscloudflare_add_ruleset_rule- Add rule to rulesetcloudflare_update_ruleset_rule- Update existing rulecloudflare_delete_ruleset_rule- Delete rule from rulesetcloudflare_list_ruleset_versions- List ruleset versionscloudflare_get_ruleset_version- Get specific versioncloudflare_get_ruleset_version_by_tag- Get version filtered by tag
Resources:
- MCP resource access via
cloudflare://docs/{relative_path}URI scheme - Documentation catalog via
cloudflare://docs-catalog/{scope}
Usage Examples
Access Documentation Resources
{
"method": "resources/read",
"params": {
"uri": "cloudflare://docs/reference/fields/reference.md"
}
}
List Documentation Files
{
"method": "tools/call",
"params": {
"name": "cloudflare_list_document_names",
"arguments": {
"category": "rulesets-api"
}
}
}
Read Documentation
{
"method": "tools/call",
"params": {
"name": "cloudflare_read_document",
"arguments": {
"relative_path": "rulesets-api/add-rule.md"
}
}
}
List Zones
{
"method": "tools/call",
"params": {
"name": "cloudflare_list_zones",
"arguments": {}
}
}
Enable Client Certificate Provisioning
{
"method": "tools/call",
"params": {
"name": "client_certificate_provisioning_enable",
"arguments": {
"zone_id": "zone_id_here",
"enabled": true
}
}
}
Add Rule to Ruleset
{
"method": "tools/call",
"params": {
"name": "cloudflare_add_ruleset_rule",
"arguments": {
"scope": "zones",
"scope_id": "zone_id_here",
"ruleset_id": "ruleset_id_here",
"action": "block",
"expression": "http.request.uri.path eq \"/admin\""
}
}
}
Architecture
The server combines both tools and resources in a single MCP server:
- Tools: Provide active Cloudflare API operations
- Resources: Provide passive access to documentation content
- Shared Context: Both use the same client and configuration
- Unified Interface: Single server for all Cloudflare-related operations
This approach is more efficient than separate servers and provides a cohesive experience for users working with Cloudflare services and documentation.
Legal & Disclaimer
Cloudflare API Usage
This project uses the Cloudflare API and is not affiliated with, endorsed by, or sponsored by Cloudflare, Inc.
- API Terms: Use of this software requires compliance with Cloudflare's Terms of Service and API Terms
- Rate Limits: Be aware of Cloudflare's API rate limits and usage policies
- API Keys: You are responsible for securing your Cloudflare API tokens and keys
- No Warranty: This software is provided as-is without any warranty
Trademark Notice
"Cloudflare" is a trademark of Cloudflare, Inc. This project uses the Cloudflare name only to identify compatibility with Cloudflare's services.
License
This project is licensed under the MIT License - see the LICENSE file for details.