Skip to content

Commit 477fdcd

Browse files
trisongztrisongz
committed
Add Cloudflare MCP server for DNS management
Introduces a Cloudflare MCP (Model Context Protocol) server that exposes DNS management tools for AI assistants. Adds server implementation, entry points, documentation, and updates project scripts and optional dependencies for MCP support.
1 parent e5d70fb commit 477fdcd

7 files changed

Lines changed: 1303 additions & 0 deletions

File tree

‎docs/api/lzl/cloudflare.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -678,6 +678,55 @@ diff = await client.adiff_dns_records(records, root_domain="example.com")
678678
comparison = await client.acompare_zones("example.com", "example.net")
679679
```
680680

681+
## MCP Server
682+
683+
The Cloudflare client includes an MCP (Model Context Protocol) server that exposes all DNS management functionality as tools for AI assistants.
684+
685+
### Quick Start
686+
687+
```bash
688+
# Install with MCP support
689+
uv pip install lazyops[cloudflare]
690+
691+
# Set credentials
692+
export CLOUDFLARE_API_TOKEN="your-api-token"
693+
694+
# Run the server
695+
uv run cloudflare-mcp
696+
```
697+
698+
### Claude Desktop Configuration
699+
700+
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
701+
702+
```json
703+
{
704+
"mcpServers": {
705+
"cloudflare": {
706+
"command": "uv",
707+
"args": ["run", "--with", "lazyops[cloudflare]", "cloudflare-mcp"],
708+
"env": {
709+
"CLOUDFLARE_API_TOKEN": "your-api-token"
710+
}
711+
}
712+
}
713+
}
714+
```
715+
716+
### Available Tools
717+
718+
The MCP server exposes 20+ tools including:
719+
720+
- **Zone Management**: `cloudflare_list_zones`, `cloudflare_get_zone`
721+
- **DNS CRUD**: `cloudflare_list_records`, `cloudflare_create_record`, `cloudflare_update_record`, `cloudflare_delete_record`
722+
- **Record Helpers**: `cloudflare_add_a_record`, `cloudflare_add_cname_record`, `cloudflare_add_mx_record`, `cloudflare_add_txt_record`
723+
- **Service Templates**: `cloudflare_add_google_workspace_mx`, `cloudflare_add_microsoft_365_mx`, `cloudflare_add_spf_record`, `cloudflare_add_dmarc_record`
724+
- **Export/Import**: `cloudflare_export_records`, `cloudflare_import_records`
725+
- **Diff/Compare**: `cloudflare_diff_records`, `cloudflare_compare_zones`
726+
- **Declarative**: `cloudflare_apply_records`
727+
728+
See the [MCP Server Guide](../../../src/lzl/api/cloudflare/MCP_SERVER.md) for full documentation.
729+
681730
## Context Manager
682731

683732
The client supports context manager usage for proper resource cleanup:

‎pyproject.toml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,15 @@ kvdb-py = { git = "https://github.com/trisongz/kvdb-py" }
4040

4141
[project.scripts]
4242
lzl = "lzl.cmd:main"
43+
cloudflare-mcp = "lzl.api.cloudflare.mcp:main"
4344

4445
[project.optional-dependencies]
46+
mcp = [
47+
"mcp>=1.0.0",
48+
]
49+
cloudflare = [
50+
"mcp>=1.0.0",
51+
]
4552
kops = [
4653
"kubernetes",
4754
"kubernetes_asyncio",

‎src/lzl/api/cloudflare/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -275,6 +275,43 @@ record = await client.dns.aupsert(zone_id, record_data)
275275
result = await client.aapply_dns_records(records, root_domain="example.com")
276276
```
277277

278+
## MCP Server
279+
280+
An MCP server is included to expose Cloudflare DNS tools to AI assistants.
281+
282+
### Quick Start
283+
284+
```bash
285+
# Install with MCP support
286+
uv pip install lazyops[cloudflare]
287+
288+
# Set credentials
289+
export CLOUDFLARE_API_TOKEN="your-api-token"
290+
291+
# Run the server
292+
uv run cloudflare-mcp
293+
```
294+
295+
### Claude Desktop Configuration
296+
297+
Add to your Claude Desktop config:
298+
299+
```json
300+
{
301+
"mcpServers": {
302+
"cloudflare": {
303+
"command": "uv",
304+
"args": ["run", "--with", "lazyops[cloudflare]", "cloudflare-mcp"],
305+
"env": {
306+
"CLOUDFLARE_API_TOKEN": "your-api-token"
307+
}
308+
}
309+
}
310+
}
311+
```
312+
313+
See [MCP_SERVER.md](mcp/README.md) for full documentation.
314+
278315
## Context Manager
279316

280317
```python

‎src/lzl/api/cloudflare/mcp/README.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# Cloudflare MCP Server
2+
3+
An MCP (Model Context Protocol) server that exposes Cloudflare DNS management functionality as tools for AI assistants like Claude.
4+
5+
## Installation
6+
7+
Install with MCP support:
8+
9+
```bash
10+
# Using pip
11+
pip install lazyops[cloudflare]
12+
13+
# Using uv
14+
uv pip install lazyops[cloudflare]
15+
```
16+
17+
## Configuration
18+
19+
Set your Cloudflare credentials as environment variables:
20+
21+
```bash
22+
# Using API Token (recommended)
23+
export CLOUDFLARE_API_TOKEN="your-api-token"
24+
25+
# Or using API Key + Email
26+
export CLOUDFLARE_API_KEY="your-api-key"
27+
export CLOUDFLARE_EMAIL="your-email@example.com"
28+
```
29+
30+
## Running the Server
31+
32+
### Using uv (Recommended)
33+
34+
```bash
35+
# Run directly with uv
36+
uv run cloudflare-mcp
37+
38+
# Or with inline dependencies
39+
uv run --with lazyops[cloudflare] cloudflare-mcp
40+
```
41+
42+
### Using Python Module
43+
44+
```bash
45+
python -m lzl.api.cloudflare.mcp
46+
```
47+
48+
### Using Entry Point (after installation)
49+
50+
```bash
51+
cloudflare-mcp
52+
```
53+
54+
## Claude Desktop Configuration
55+
56+
Add to your Claude Desktop configuration file:
57+
58+
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
59+
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
60+
61+
```json
62+
{
63+
"mcpServers": {
64+
"cloudflare": {
65+
"command": "uv",
66+
"args": ["run", "--with", "lazyops[cloudflare]", "cloudflare-mcp"],
67+
"env": {
68+
"CLOUDFLARE_API_TOKEN": "your-api-token"
69+
}
70+
}
71+
}
72+
}
73+
```
74+
75+
Or if you have `lazyops` installed globally:
76+
77+
```json
78+
{
79+
"mcpServers": {
80+
"cloudflare": {
81+
"command": "cloudflare-mcp",
82+
"env": {
83+
"CLOUDFLARE_API_TOKEN": "your-api-token"
84+
}
85+
}
86+
}
87+
}
88+
```
89+
90+
## Available Tools
91+
92+
### Zone Management
93+
94+
| Tool | Description |
95+
|------|-------------|
96+
| `cloudflare_list_zones` | List all zones in the account |
97+
| `cloudflare_get_zone` | Get details for a specific zone |
98+
99+
### DNS Record Operations
100+
101+
| Tool | Description |
102+
|------|-------------|
103+
| `cloudflare_list_records` | List DNS records for a zone |
104+
| `cloudflare_create_record` | Create a new DNS record |
105+
| `cloudflare_update_record` | Update an existing record |
106+
| `cloudflare_delete_record` | Delete a DNS record |
107+
108+
### Record Type Helpers
109+
110+
Convenience tools for common record types:
111+
112+
| Tool | Description |
113+
|------|-------------|
114+
| `cloudflare_add_a_record` | Add an A record (IPv4) |
115+
| `cloudflare_add_aaaa_record` | Add an AAAA record (IPv6) |
116+
| `cloudflare_add_cname_record` | Add a CNAME record |
117+
| `cloudflare_add_mx_record` | Add an MX record |
118+
| `cloudflare_add_txt_record` | Add a TXT record |
119+
120+
### Service Templates
121+
122+
Pre-configured email service setups:
123+
124+
| Tool | Description |
125+
|------|-------------|
126+
| `cloudflare_add_google_workspace_mx` | Add Google Workspace MX records |
127+
| `cloudflare_add_microsoft_365_mx` | Add Microsoft 365 MX record |
128+
| `cloudflare_add_spf_record` | Add SPF record with provider presets |
129+
| `cloudflare_add_dmarc_record` | Add DMARC record |
130+
131+
### Export / Import
132+
133+
| Tool | Description |
134+
|------|-------------|
135+
| `cloudflare_export_records` | Export records to JSON or BIND format |
136+
| `cloudflare_import_records` | Import records from JSON |
137+
138+
### Diff / Compare
139+
140+
| Tool | Description |
141+
|------|-------------|
142+
| `cloudflare_diff_records` | Preview changes without applying |
143+
| `cloudflare_compare_zones` | Compare records between two zones |
144+
145+
### Declarative Management
146+
147+
| Tool | Description |
148+
|------|-------------|
149+
| `cloudflare_apply_records` | Apply desired DNS state declaratively |
150+
151+
## Example Prompts
152+
153+
Once connected, you can ask Claude:
154+
155+
- "List all my Cloudflare zones"
156+
- "Show me the DNS records for example.com"
157+
- "Add an A record pointing www.example.com to 192.0.2.1"
158+
- "Set up Google Workspace email for example.com"
159+
- "Add SPF and DMARC records for example.com"
160+
- "Export all DNS records from example.com"
161+
- "Compare DNS records between staging.example.com and example.com"
162+
163+
## Security Notes
164+
165+
- The server uses your Cloudflare credentials from environment variables
166+
- All operations are performed with the permissions of your API token
167+
- Use API tokens with minimal required permissions when possible
168+
- The `sync_mode="full"` option in `cloudflare_apply_records` can delete records - use with caution
169+
170+
## Troubleshooting
171+
172+
### Server won't start
173+
174+
1. Ensure credentials are set:
175+
```bash
176+
echo $CLOUDFLARE_API_TOKEN
177+
```
178+
179+
2. Verify the MCP package is installed:
180+
```bash
181+
uv pip show mcp
182+
```
183+
184+
3. Test the server manually:
185+
```bash
186+
uv run cloudflare-mcp
187+
```
188+
189+
### Permission errors
190+
191+
Ensure your API token has the required permissions:
192+
- `Zone:Read` - For listing zones
193+
- `DNS:Read` - For listing records
194+
- `DNS:Edit` - For creating/updating/deleting records
195+
196+
### Connection issues
197+
198+
Check that your `claude_desktop_config.json` is valid JSON and the paths are correct.

‎src/lzl/api/cloudflare/mcp/__init__.py‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
"""
2+
Cloudflare MCP Server
3+
4+
An MCP (Model Context Protocol) server that exposes Cloudflare DNS management
5+
functionality as tools for AI assistants.
6+
7+
Usage:
8+
uv run cloudflare-mcp
9+
10+
Or directly:
11+
python -m lzl.api.cloudflare.mcp
12+
"""
13+
14+
from .server import serve, create_server, main
15+
16+
__all__ = ["serve", "create_server", "main"]

‎src/lzl/api/cloudflare/mcp/__main__.py‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
"""
2+
Entry point for running the Cloudflare MCP server as a module.
3+
4+
Usage:
5+
python -m lzl.api.cloudflare.mcp
6+
"""
7+
8+
from .server import main
9+
10+
if __name__ == "__main__":
11+
main()

0 commit comments

Comments
 (0)