# 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:
```bash
git clone https://github.com/quareth/cloudflare_waf_mcp.git
cd cloudflare_waf_mcp
```
2. (Recommended) Create and activate a virtual environment:
```bash
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
```
3. Install dependencies:
```bash
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:*
```json
{
"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:*
```json
{
"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):**
```json
{
"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:*
```bash
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:*
```bash
/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:**
```json
{
"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)**
```bash
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:
```bash
export CLOUDFLARE_API_TOKEN="your_token_here"
```
5. Run the server:
**Standard mode (stdio):**
```bash
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.
```bash
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](https://modelcontextprotocol.io/specification/2025-06-18/server/resources), 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
```json
{
"method": "resources/read",
"params": {
"uri": "cloudflare://docs/reference/fields/reference.md"
}
}
```
### List Documentation Files
```json
{
"method": "tools/call",
"params": {
"name": "cloudflare_list_document_names",
"arguments": {
"category": "rulesets-api"
}
}
}
```
### Read Documentation
```json
{
"method": "tools/call",
"params": {
"name": "cloudflare_read_document",
"arguments": {
"relative_path": "rulesets-api/add-rule.md"
}
}
}
```
### List Zones
```json
{
"method": "tools/call",
"params": {
"name": "cloudflare_list_zones",
"arguments": {}
}
}
```
### Enable Client Certificate Provisioning
```json
{
"method": "tools/call",
"params": {
"name": "client_certificate_provisioning_enable",
"arguments": {
"zone_id": "zone_id_here",
"enabled": true
}
}
}
```
### Add Rule to Ruleset
```json
{
"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](https://www.cloudflare.com/terms/) and [API Terms](https://developers.cloudflare.com/fundamentals/api/reference/terms-of-service/)
- **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](LICENSE) file for details.
