cloudflare-mcp-server

ry-ops/cloudflare-mcp-server

3.3

If you are the rightful owner of cloudflare-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Cloudflare MCP Server is a Model Context Protocol server that integrates with the Cloudflare API to manage resources such as zones, DNS records, Workers KV storage, cache purging, and analytics.

Tools
5
Resources
0
Prompts
0

Python uv MCP

Cloudflare MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with the Cloudflare API. Built with Python and managed with uv for blazing-fast dependency management.

Features

🌐 Zone Management

  • List all zones in your account
  • Get detailed zone information
  • Filter zones by name and status

🔧 DNS Management

  • List DNS records with filtering
  • Create new DNS records (A, AAAA, CNAME, TXT, MX, etc.)
  • Update existing records
  • Delete records
  • Full support for proxied records and TTL configuration

💾 Workers KV Storage

  • List KV namespaces
  • Read values from KV
  • Write key-value pairs with optional TTL
  • Delete keys
  • List keys with prefix filtering
  • Support for metadata

⚡ Cache & Performance

  • Purge cache (entire zone or specific files/tags/hosts)
  • Get zone analytics (requests, bandwidth, threats)

Installation

Prerequisites

  • Python 3.10 or higher
  • uv installed
  • A Cloudflare account with an API token

Quick Start with uv

  1. Clone or create the project:
mkdir cloudflare-mcp-server
cd cloudflare-mcp-server
  1. Install with uv:
uv pip install -e .

Or install from the directory:

uv pip install cloudflare-mcp-server

Alternative: Using pip

pip install -e .

Configuration

Getting Your Cloudflare Credentials

  1. API Token (Required):

    • Go to Cloudflare Dashboard
    • Click "Create Token"
    • Use "Edit zone DNS" template or create a custom token with the permissions you need
    • Copy the token

  2. Account ID (Optional, but required for KV operations):

    • Go to your Cloudflare dashboard
    • Select any website
    • Scroll down on the Overview page to find your Account ID

Environment Variables

Set the following environment variables:

export CLOUDFLARE_API_TOKEN="your_api_token_here"
export CLOUDFLARE_ACCOUNT_ID="your_account_id_here"  # Optional, needed for KV

Or create a .env file (see .env.example).

Claude Desktop Configuration

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Using uv (recommended):
{
  "mcpServers": {
    "cloudflare": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/cloudflare-mcp-server",
        "run",
        "cloudflare-mcp-server"
      ],
      "env": {
        "CLOUDFLARE_API_TOKEN": "your_api_token_here",
        "CLOUDFLARE_ACCOUNT_ID": "your_account_id_here"
      }
    }
  }
}
Using Python directly:
{
  "mcpServers": {
    "cloudflare": {
      "command": "python",
      "args": ["-m", "cloudflare_mcp_server"],
      "env": {
        "CLOUDFLARE_API_TOKEN": "your_api_token_here",
        "CLOUDFLARE_ACCOUNT_ID": "your_account_id_here"
      }
    }
  }
}

Available Tools

The server provides 13 powerful tools for managing Cloudflare resources:

Zone Operations

  • list_zones - List all zones (domains) with optional filtering
  • get_zone - Get detailed information about a specific zone

DNS Operations

  • list_dns_records - List DNS records with filtering
  • create_dns_record - Create new DNS records
  • update_dns_record - Update existing DNS records
  • delete_dns_record - Delete DNS records

Cache Operations

  • purge_cache - Purge cached content (entire zone or specific files/tags/hosts)

Workers KV Operations

  • list_kv_namespaces - List all KV namespaces
  • read_kv_value - Read a value from KV storage
  • write_kv_value - Write a key-value pair to KV
  • delete_kv_value - Delete a key from KV
  • list_kv_keys - List all keys in a namespace

Analytics

  • get_zone_analytics - Get analytics data for a zone

For detailed documentation on each tool, see .

Agent-to-Agent (A2A) Protocol Support

This MCP server implements the Agent-to-Agent (A2A) protocol, enabling seamless communication between AI agents and autonomous systems. The A2A protocol standardizes how agents discover capabilities, authenticate, and execute operations across distributed systems.

Agent Card

The agent card is located at agent-card.json in the root directory. It provides a machine-readable description of:

  • Agent capabilities: Streaming support, async operations, task management
  • Available skills: 5 skill categories with 13 operations total
  • Authentication requirements: Bearer token configuration
  • Transport protocols: stdio-based communication via uv or Python
  • API schema: Complete parameter definitions for all operations

Skills for Agent-to-Agent Communication

The Cloudflare MCP Agent exposes the following skills through the A2A protocol:

1. Zone Management

Manage Cloudflare zones (domains) including listing and detailed queries.

  • list_zones - List all zones with filtering options
  • get_zone - Retrieve detailed zone information
2. DNS Management

Comprehensive DNS record operations supporting all record types (A, AAAA, CNAME, TXT, MX, etc.).

  • list_dns_records - Query DNS records with filters
  • create_dns_record - Create new DNS records with Cloudflare proxy support
  • update_dns_record - Modify existing DNS records
  • delete_dns_record - Remove DNS records
3. Workers KV Storage

Distributed key-value storage with metadata and TTL support.

  • list_kv_namespaces - List all KV namespaces
  • read_kv_value - Retrieve values by key
  • write_kv_value - Store key-value pairs with optional expiration
  • delete_kv_value - Delete keys
  • list_kv_keys - List keys with prefix filtering
4. Cache Management

Cloudflare cache purging and invalidation.

  • purge_cache - Purge by zone, files, tags, or hosts
5. Analytics

Zone performance metrics and analytics.

  • get_zone_analytics - Get requests, bandwidth, threats, and pageviews

A2A Integration Examples

Example 1: Agent-to-Agent DNS Management

An orchestrator agent can delegate DNS management to this Cloudflare agent:

{
  "agent": "cloudflare-mcp-agent",
  "skill": "dns_management",
  "operation": "create_dns_record",
  "parameters": {
    "zone_id": "abc123",
    "type": "A",
    "name": "api",
    "content": "192.0.2.100",
    "proxied": true
  }
}
Example 2: Multi-Agent Cache Invalidation

A deployment agent can coordinate with this Cloudflare agent for cache invalidation:

{
  "workflow": "deploy-and-invalidate",
  "steps": [
    {
      "agent": "deployment-agent",
      "action": "deploy_assets"
    },
    {
      "agent": "cloudflare-mcp-agent",
      "skill": "cache_management",
      "operation": "purge_cache",
      "parameters": {
        "zone_id": "abc123",
        "files": ["https://example.com/app.js", "https://example.com/style.css"]
      }
    }
  ]
}
Example 3: KV Storage for Inter-Agent Communication

Agents can use KV storage for shared state:

{
  "agent": "cloudflare-mcp-agent",
  "skill": "kv_storage",
  "operation": "write_kv_value",
  "parameters": {
    "namespace_id": "kv123",
    "key": "agent-state:orchestrator",
    "value": "{\"status\": \"processing\", \"tasks\": 5}",
    "metadata": {
      "agent": "orchestrator-v1",
      "timestamp": "2025-12-08T15:00:00Z"
    }
  }
}

A2A Authentication

When integrating with other agents, ensure the following environment variables are set:

export CLOUDFLARE_API_TOKEN="your_api_token_here"
export CLOUDFLARE_ACCOUNT_ID="your_account_id_here"  # Required for KV operations

The agent card specifies the minimum and recommended Cloudflare API permissions required for different operations.

Discovering Agent Capabilities

Other agents can discover this agent's capabilities by reading the agent-card.json file:

import json

# Load agent card
with open("agent-card.json") as f:
    agent_card = json.load(f)

# Discover available skills
for skill in agent_card["skills"]:
    print(f"Skill: {skill['name']}")
    for operation in skill["operations"]:
        print(f"  - {operation['name']}: {operation['description']}")

A2A Protocol Compliance

This agent implements the following A2A protocol features:

  • Structured agent card with capabilities and skills
  • Standardized skill and operation definitions
  • Type-safe parameter schemas
  • Authentication and authorization declarations
  • Transport protocol specifications (stdio)
  • Error handling and status reporting via MCP

For more information on the A2A protocol, see the agent card specification in agent-card.json.

Development

Using uv for Development

# Install in development mode with dev dependencies
uv pip install -e ".[dev]"

# Run the server directly
uv run cloudflare-mcp-server

# Run tests (when implemented)
uv run pytest

# Format code with ruff
uv run ruff format src/

# Lint code
uv run ruff check src/

Project Structure

cloudflare-mcp-server/
├── src/
│   └── cloudflare_mcp_server/
│       └── __init__.py       # Main server implementation
├── tests/                     # Tests (to be implemented)
├── pyproject.toml            # Project configuration (uv-compatible)
├── README.md                 # This file
├── QUICKSTART.md            # Quick start guide
├── EXAMPLES.md              # Usage examples
└── .env.example             # Environment template

Usage Examples

Example 1: List Your Zones

Ask Claude:

"Show me all my Cloudflare zones"

Example 2: Create a DNS Record

Ask Claude:

"Create an A record for api.example.com pointing to 192.0.2.100 with proxy enabled"

Example 3: Purge Cache

Ask Claude:

"Clear the cache for https://example.com/style.css"

For more examples, see .

API Permissions

Your Cloudflare API token needs appropriate permissions based on what operations you want to perform:

Minimum Permissions:

  • Zone - Zone - Read (for listing zones)
  • Zone - DNS - Edit (for DNS operations)

Additional Permissions for Advanced Features:

  • Account - Workers KV Storage - Edit (for KV operations)
  • Zone - Cache Purge - Purge (for cache operations)
  • Zone - Analytics - Read (for analytics)

Troubleshooting

Common Issues

  1. "CLOUDFLARE_API_TOKEN environment variable is required"

    • Make sure you've set the environment variable
    • Check your Claude Desktop config has the correct token in the env section

  2. "Account ID is required"

    • Set CLOUDFLARE_ACCOUNT_ID environment variable for KV operations
    • Or pass account_id parameter directly in tool calls

  3. uv command not found

    • Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
    • Or use pip as an alternative

  4. Module not found errors

    • Make sure you installed the package: uv pip install -e .
    • Check you're in the right directory

Why uv?

This project uses uv because it's:

  • ⚡ 10-100x faster than pip
  • 🔒 More reliable with better dependency resolution
  • 🎯 Simpler - one tool for everything
  • 🐍 Modern - built in Rust, designed for Python

Security Notes

  • Never commit your API token to version control
  • Store tokens securely using environment variables
  • Use API tokens instead of API keys (they're more secure and can be scoped)
  • Regularly rotate your API tokens
  • Use the minimum required permissions for your token

Contributing

Contributions are welcome! See for guidelines.

License

MIT License - see file for details.

Links

Support

For issues related to: