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-engine folder 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

1. Clone the repository:

git clone https://github.com/quareth/cloudflare_waf_mcp.git
cd cloudflare_waf_mcp

2. (Recommended) Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

pip install --upgrade pip
pip install -r requirements.txt

4. 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:

1. 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

2. 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"

5. 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):

1. MCP Client env section (if configured in MCP client)
2. System environment variables (e.g., export CLOUDFLARE_API_TOKEN=...)
3. .env file in the project root

Security Considerations

MCP Client Configuration (env section):

• ✅ Pros: Convenient, no separate .env file 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 env section is fine
• For shared systems or CI/CD: Use environment variables or .env file (and ensure .env is 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 list should show fastmcp installed

• "ENOENT" or "The system cannot find the path specified":

  • The venv path in MCP config is incorrect
  • Solution: Check if your venv is named venv or .venv and 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_TOKEN has the necessary permissions (e.g., WAF/Rulesets write for rule creation).

• Documentation not found: Set CLOUDFLARE_DOCS_ROOT environment variable to the absolute path of src/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 accounts
  • cloudflare_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 files
• cloudflare://docs/reference/field-name.md - Access reference documentation
• cloudflare://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 changes
• resources.listChanged: Notifications when resource list changes

Resource Operations

• resources/list: List all available documentation resources
• resources/read: Read specific documentation content
• resources/templates/list: List resource templates for dynamic access

Resource Annotations

• audience: ["user", "assistant"] - Content useful for both
• priority: 0.5-0.7 - Importance level (reference docs have higher priority)
• lastModified: ISO 8601 timestamp

Actual Implemented Features

Tools (14 total):

1. cloudflare_list_document_names - List documentation files
2. cloudflare_read_document - Read documentation content
3. cloudflare_list_zones - List Cloudflare zones
4. cloudflare_get_zone_details - Get zone details
5. cloudflare_list_accounts - List Cloudflare accounts
6. client_certificate_provisioning_enable - Enable/disable client certificate provisioning for Device Information Only mode
7. cloudflare_list_rulesets - List rulesets
8. cloudflare_get_ruleset - Get ruleset details
9. cloudflare_add_ruleset_rule - Add rule to ruleset
10. cloudflare_update_ruleset_rule - Update existing rule
11. cloudflare_delete_ruleset_rule - Delete rule from ruleset
12. cloudflare_list_ruleset_versions - List ruleset versions
13. cloudflare_get_ruleset_version - Get specific version
14. cloudflare_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.