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:

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

3. Install dependencies:

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:

Linux/Mac:

Using System Python (if dependencies installed globally):

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:

Linux/Mac:

2. Configure MCP client to connect via URL:

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)

Option C: System Environment Variables Set environment variables in your shell:

5. Run the server:

Standard mode (stdio):

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.

Configuration Priority

The server reads configuration in this order (first found wins):

1. MCP Client (if configured in MCP client)

2. System environment variables (e.g., export CLOUDFLARE_API_TOKEN=...)

3. .env in the project root

Security Considerations

MCP Client Configuration (

• ✅ 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 /

• ✅ 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

List Documentation Files

Read Documentation

List Zones

Enable Client Certificate Provisioning

Add Rule to Ruleset

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.