内容
# CaddyUI MCP
一款适用于 **[CaddyUI](https://github.com/X4Applegate/caddyui)** 的 [MCP](https://modelcontextprotocol.io) 服务器 —— CaddyUI 自托管 Web UI 的反向代理。 它允许 MCP 客户端（Claude 等）以自然语言检查和管理您的 Caddy 配置：代理主机，重定向主机，原始路由和 TLS 证书。
它封装了 CaddyUI 的稳定、版本化的 **REST API（`/api/v1`）** （在 CaddyUI v2.13 中添加），使用 API 令牌（`Authorization: Bearer <token>`）进行身份验证。 CaddyUI 自己的 SQLite 数据库是真实来源；它将生成的配置推送到 Caddy 的管理 API —— 因此该服务器与 CaddyUI 通信，而不是直接与 Caddy 通信。
## 工具
| 资源 | 工具 |
| --- | --- |
| **服务器** | `list_caddy_servers` |
| **代理主机** | `list_proxy_hosts`, `get_proxy_host`, `create_proxy_host`, `update_proxy_host`, `delete_proxy_host`, `toggle_proxy_host`, `set_proxy_host_maintenance` |
| **重定向主机** | `list_redirection_hosts`, `get_redirection_host`, `create_redirection_host`, `update_redirection_host`, `delete_redirection_host`, `toggle_redirection_host` |
| **原始路由** | `list_raw_routes`, `get_raw_route`, `create_raw_route`, `update_raw_route`, `delete_raw_route`, `toggle_raw_route` |
| **证书** | `list_certificates`, `get_certificate`, `create_certificate`, `update_certificate`, `delete_certificate` |
| **状态**（只读） | `caddy_version`, `system_stats`, `upstream_health`, `search` |
创建/更新工具需要一个 JSON `config` 对象。 代理主机模型有 200 多个可选字段，因此预期的工作流程是 **`get_*` 现有对象，然后修改并重新发送** —— 服务器的指令告诉 LLM 准确地这样做。
### 多服务器
CaddyUI 可以集中管理 **多个 Caddy 实例**，并且每个资源都限定在一个服务器上。 几乎所有工具都采用可选的 **`server_id`**；省略它会针对 CaddyUI 的 **默认服务器（1）**，即使其他服务器已满，它也可能为空。 首先调用 **`list_caddy_servers`** —— 它会探测服务器 ID 并报告哪些服务器包含代理主机（带有示例域名，您可以从中区分它们）——然后将选定的 `server_id` 传递给其他工具。 （服务器选择使用 CaddyUI 的 `caddyui_server` cookie；没有记录的 API 参数。）
## 配置
配置通过环境变量（12 因子）。 复制 [`.env.example`](.env.example) 到 `.env`：
| 变量 | 必需 | 描述 |
| --- | --- | --- |
| `CADDYUI_URL` | 是 | CaddyUI 基本 URL，例如 `https://caddyui.example.com`（默认为 `https://caddyui.strant.casa`）。 |
| `CADDYUI_TOKEN` | 是 | CaddyUI 在 `/api-tokens` 处生成的 API 令牌。范围 `full`（所有 CRUD），`proxy_write`（仅代理主机），或 `read_only`。 |
| `MCP_HTTP_PORT` | 否 | Web 入口点的端口（默认为 `8080`）。 |
| `LOG_LEVEL` | 否 | `DEBUG`/`INFO`/`WARNING`/`ERROR`（默认为 `INFO`）。 |
### 获取令牌
在 CaddyUI 中，打开 **API 令牌**（`/api-tokens`），创建具有所需范围的令牌，然后复制它（仅显示一次）。 对于完全的读写管理，请使用 `full`。
## 使用 Docker 运行
```bash
cp .env.example .env # 然后设置 CADDYUI_URL 和 CADDYUI_TOKEN
docker compose up -d --build
docker compose ps # STATUS 应该变为 "healthy"
```
服务器在 `:8080` 上侦听，并通过 **Streamable HTTP** 在 `http://<host>:8080/mcp` 上提供 MCP 服务。 容器的 `HEALTHCHECK` 执行完整的 MCP 握手并调用 `list_proxy_hosts`，因此只有在 CaddyUI 实际可达且令牌有效时，它才会报告健康状态（空的 CaddyUI 也算健康）。
一旦注册表镜像发布，请在 `compose.yaml` 中固定它：
```yaml
image: ghcr.io/loryanstrant/caddyui-mcp:latest
```
## 连接 MCP 客户端
将您的客户端指向 Streamable HTTP 端点（注意：`/mcp`，没有尾部斜杠）：
```json
{
"mcpServers": {
"caddyui": { "type": "http", "url": "http://<host>:8080/mcp" }
}
}
```
对于_stdio 客户端，请使用相同的环境运行 `caddyui-mcp`（而不是 Web 入口点）。
## 开发
```bash
make install-dev # venv + deps
make check # lint + format-check + typecheck + test
# 针对真实的 CaddyUI 进行实时测试（创建和删除一个临时代理主机）：
CADDYUI_URL=https://caddyui.example.com CADDYUI_TOKEN=cadu_... .venv/bin/pytest -m live
```
## 许可证
[MIT](LICENSE)。
