caddy-mcp-server/README.md

Caddy MCP Server

A comprehensive Model Context Protocol (MCP) server for managing Caddy web server via the Admin API.

Features

Complete Caddy management with 21 powerful tools:

Site Management

Tool	Description
list_sites	List all configured sites with upstreams & auth status
get_site	Get detailed configuration for a specific site
get_site_routes	Get all routes (including path-based) for a site
add_site	Add a new site with reverse proxy
remove_site	Remove a site configuration
update_upstream	Update the upstream address for a site

Path-Based Routing

Tool	Description
add_path_route	Add path-based route (e.g., /api/* → localhost:3000)
remove_path_route	Remove a path-based route

Authentication

Tool	Description
add_basic_auth	Add basic authentication to a site
remove_basic_auth	Remove basic authentication

Headers

Tool	Description
add_request_header	Add header sent to upstream
add_response_header	Add header sent to client

File Server

Tool	Description
add_file_server	Add static file server
update_file_root	Update file server root directory

Review Environments

Tool	Description
add_wip_environment	Add WIP review env to review.example.com

Configuration

Tool	Description
export_config	Export full Caddy JSON config
adapt_caddyfile	Convert Caddyfile to JSON
validate_config	Validate config without applying

Server Control

Tool	Description
caddy_status	Check Caddy health
stop_caddy	Gracefully stop Caddy

Usage

# Build
go build -o caddy-mcp .

# Run locally
./caddy-mcp

# Run against remote Caddy (via SSH tunnel)
ssh -L 2019:localhost:2019 server-1 &
./caddy-mcp

Environment

• CADDY_HOST - Caddy admin API host (default: localhost:2019)
• REVIEW_DOMAIN - Domain for WIP review environments (default: review.example.com)

Architecture

Input Validation (validators.go)

The server includes comprehensive input validation to prevent security issues:

• Domain validation: Ensures valid domain format

• Path validation: Prevents directory traversal attacks

• Port validation: Validates port ranges (1-65535)

• Header validation: Validates HTTP header names

• client.go - Caddy Admin API client

• server.go - MCP server setup

• handlers.go - Tool implementations

• site_ops.go - Site read operations

• site_modify.go - Site write operations

• path_routes.go - Path-based routing

• auth_ops.go - Authentication management

• headers.go - Header manipulation

• fileserver.go - Static file serving

Security

Password Transmission

WARNING: Passwords are transmitted in plaintext from the MCP client to this server. This is an architectural limitation of the Model Context Protocol (MCP). While Caddy stores passwords hashed (bcrypt), the password travels unencrypted through the MCP communication channel.

Caddy Admin API

The Caddy admin API (localhost:2019 by default) uses HTTP, not HTTPS. When running this MCP server remotely, use SSH port forwarding to secure the connection:

ssh -L 2019:localhost:2019 <remote-server> &
./caddy-mcp

Examples

# List all sites
./caddy-mcp
# Send: {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_sites","arguments":{}}}

# Add a WIP environment
# {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"add_wip_environment","arguments":{"project":"my-project","port":3000}}}

---

Built with ❤️ by Karti AI