Loading... # EZBT-MCP：宝塔面板 MCP 服务架构与使用指南 # 一、背景与目标 ## 1. 项目背景 ### A. 业务场景 宝塔 Linux 面板（BT Panel）是广泛使用的服务器运维面板，提供网站、数据库、Docker、文件等管理能力。日常运维中，管理员需要在浏览器中登录面板执行操作，或通过宝塔提供的 HTTP API 自行对接。若希望用自然语言驱动运维（例如在 AI 编辑器中说出「帮我看看这台服务器的 CPU 和内存」「把站点 example.com 停用一下」），就需要将面板能力以「工具」形式暴露给 AI，并遵循统一的协议。 ### B. 痛点分析 - 面板能力与 AI 对话之间缺少标准桥梁，难以被 Cursor、Claude Code 等编辑器直接调用。 - 自行对接宝塔 API 时需处理签名、Cookie、参数封装，重复造轮子。 - 希望用同一套协议同时支持多种 AI 客户端，便于扩展与复用。 ## 2. 设计目标 ### A. 功能目标 - 基于 Model Context Protocol（MCP）将宝塔面板核心能力封装为工具，供 AI 通过自然语言调用。 - 覆盖系统监控、网站管理、文件操作、数据库、Docker、邮件等常用场景。 - 提供清晰的工具列表与参数说明，便于集成与二次开发。 ### B. 非功能目标 - 鉴权符合宝塔官方签名算法，每次请求按当前时间计算 token，长时间运行无需重启。 - 支持 stdio 与 SSE 两种传输方式，适配不同 MCP 客户端。 - 代码结构清晰，按模块划分（system、sites、files、docker 等），便于维护与扩展。 # 二、总体设计 ## 1. 设计原则 - 工具与宝塔 API 一一对应或聚合对应，避免过度封装导致语义失真。 - 所有请求经统一 HTTP 封装层（panelHttpController），统一处理 BaseURL、签名与表单编码。 - 无状态设计，不维护会话状态，依赖环境变量配置面板地址与 API 密钥。 ## 2. 系统架构 ```mermaid graph TB subgraph 客户端 AI[AI 编辑器 / Cursor 等] end subgraph ezbt-mcp MCP[MCP Server] SYS[system 模块] SIT[sites 模块] FIL[files 模块] DB[databases 模块] DOCK[docker 模块] EMAIL[email 模块] UTIL[utils 鉴权与 HTTP] end subgraph 宝塔面板 BT[宝塔 Linux 面板 API] end AI -->|stdio / SSE| MCP MCP --> SYS MCP --> SIT MCP --> FIL MCP --> DB MCP --> DOCK MCP --> EMAIL SYS --> UTIL SIT --> UTIL FIL --> UTIL DB --> UTIL DOCK --> UTIL EMAIL --> UTIL UTIL -->|POST + 签名| BT ```  ## 3. 组件说明 - MCP Server：基于 mcp-go 创建服务，注册全部工具并支持 stdio/SSE。 - system：系统监控类工具（公共配置、实时 CPU/内存/网络/负载、系统统计、磁盘、安装任务数）。 - sites：网站全生命周期（列表、创建、删除、停用/启用、备注、备份、域名、伪静态）。 - files：文件读写、保存、权限、创建文件/目录、删除。 - databases：MySQL 数据库列表。 - docker：容器列表与详情、本地镜像列表。 - email：邮箱创建与邮件列表。 - utils：封装 BaseURL、API 密钥读取，以及按当前时间计算 request_time 与 request_token，并统一发起 POST 请求。 # 三、核心实现 ## 1. 鉴权与请求封装 宝塔 API 要求每次请求携带 request_time（当前 Unix 时间戳）与 request_token。request_token 计算方式为：md5(string(request_time) + md5(api_sk))。ezbt-mcp 在 utils 层实现该算法，并在每次调用面板时重新计算，因此无需保存 token，长时间运行也不会因过期而失败。 请求统一使用 POST，Content-Type 为 application/x-www-form-urlencoded，参数与宝塔官方文档一致。面板地址与 api_sk 通过环境变量 BT_BASE_URL、BT_API_TOKEN 注入。 ## 2. 工具注册模式 每个能力对应一个「工具定义」和一个「处理函数」。例如 get_system_total 工具描述为「获取系统基础统计：操作系统、面板版本、CPU 核心数、内存等」，处理函数内构造 NewBTPanel，调用 system?action=GetSystemTotal，无额外参数。需要参数的例如 add_site，工具定义中声明必填参数 domains（多个域名逗号分隔），处理函数中解析参数、组装 webname 等字段再请求 site?action=AddSite。这种模式便于与 MCP-TOOLS.md、api.md 对照，也便于新增工具时保持风格一致。 ## 3. 模块划分与 API 映射 - 系统：get_public_config、get_network、get_system_total、get_disk_info、get_task_count 分别对应面板公共配置、GetNetWork、GetSystemTotal、GetDiskInfo、GetTaskCount。 - 网站：get_sites_list 使用 datalist/data/get_data_list（table=sites），add_site、delete_site、site_stop、site_start、set_site_ps、备份与域名、get_rewrite_list 等对应 api.md 中站点与数据接口。 - 文件：get_file_content、save_file_content、set_file_permissions、create_file、create_dir、delete_file 对应 files 相关 action。 - 数据库、Docker、邮件：均通过同一 utils 层请求面板对应接口，实现见各模块源码。 # 四、使用指南 ## 1. 环境要求 - Go 1.18+（若从源码构建）。 - 已安装并开启 API 接口的宝塔 Linux 面板。 - 在面板「设置 → API 接口」中获取 api_sk，并将调用方 IP 加入白名单（无固定 IP 时可填 *，需注意安全）。 ## 2. 安装与运行 - 推荐方式：在 AI 编辑器中提交「请你阅读项目仓库地址帮我将这个 MCP 安装好」，由 AI 按仓库说明完成克隆与构建。 - 手动方式：克隆仓库后执行 go build -o build/mcp-ezbt.exe main.go（Windows 示例），得到可执行文件。 ## 3. 编辑器配置 在 Cursor、Trae 等支持的 MCP 配置中增加： - command：指向编译得到的 mcp-ezbt 可执行文件路径。 - env：BT_BASE_URL 为面板地址（如 http://1.2.3.4:8888），BT_API_TOKEN 为 api_sk。 保存后重启或重载 MCP，即可在对话中通过自然语言使用「查看系统状态」「列出网站」「创建站点」「读某个文件」等能力。 ## 4. 运行模式 - 默认 stdio 模式：MCP 客户端通过标准输入输出与进程通信，适合 Cursor 等集成方式。 - -sse 模式：启动后监听本地端口（如 8080），可通过 SSE 连接进行调试或二次对接。通过 -V 或 -version 可查看版本与构建时间。 # 五、技术选型 ## 1. 技术栈 - 语言：Go，便于单二进制分发与跨平台编译。 - MCP 实现：mcp-go（mark3labs），提供 Server、Tool、Stdio/SSE 支持。 - 与面板通信：标准库 net/http，表单编码与 MD5 签名自实现，无额外依赖。 ## 2. 选型理由 - MCP 是新兴的「模型与工具」协议，被多款 AI 编辑器支持，用 MCP 暴露宝塔能力可复用同一套工具在不同客户端使用。 - Go 静态编译、无运行时依赖，适合作为本地 MCP 服务；mcp-go 与官方 MCP 规范对齐，维护成本低。 - 不引入额外缓存或队列，所有请求实时计算签名并直达面板，逻辑简单、行为可预期。 # 六、安全与运维建议 - 务必在面板 API 白名单中限制可访问 IP，避免 api_sk 泄露后被滥用。 - BT_BASE_URL 若为内网地址，则 MCP 与面板间流量不出网；若经公网，建议面板侧启用 HTTPS 并限制端口。 - 敏感操作（如删除站点、删除文件）由 AI 调用工具执行，建议在测试环境先验证话术与参数，再在生产环境使用。 # 七、参考资料 1. [ezbt-mcp 项目仓库](https://github.com/XiaoLuoTian189/ezbt-mcp) 2. [Model Context Protocol 规范](https://modelcontextprotocol.io/) 3. 项目内 docs/MCP-TOOLS.md（工具列表与参数）、docs/api.md（宝塔 API 说明） 最后修改：2026 年 02 月 25 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏