mcp-1panel

全功能 1Panel MCP Server（Python 手写实现），对接 1Panel v2 REST API，通过 streamable-http 暴露，配合 mcphub 聚合使用。

特性

• 全功能覆盖：手写实现 490+ 个 MCP 工具，覆盖 1Panel openapi.json 的核心运维场景
• 模块化分组：工具按 <模块>_<动作> 命名（container_search/website_create/database_mysql_list），便于 mcphub Smart Routing 向量搜索召回
• streamable-http 传输：MCP 官方新标准，容器化部署友好，service 名直连
• 读写安全分层：读操作无限制；写操作受 PANEL_READONLY 控制；高危操作（delete/remove）强制 confirm 参数
• mcphub 集成：开箱即用的 docker-compose（mcphub + onepanel-mcp + postgres），启用 pgvector 向量搜索

模块覆盖

快速开始

方式一：docker-compose（推荐，含 mcphub）

# 1. 克隆并配置
cp .env.example .env
# 编辑 .env，填入 1Panel 面板地址和 API Key

# 2. 启动全部服务
docker compose up -d --build

# 3. 访问 mcphub dashboard
# 浏览器打开 http://localhost:3000

docker-compose.yml 包含三个服务：

• mcphub（端口 3000）：MCP 网关 + dashboard + smart routing
• onepanel-mcp（端口 8000，仅容器内网）：本 MCP server
• postgres（pgvector）：mcphub smart routing 向量搜索依赖

方式二：本地运行（开发调试）

# 安装依赖
make install  # 或 uv sync --extra dev

# 配置环境变量
export PANEL_ENDPOINT="http://192.168.1.2:39579"
export PANEL_API_KEY="your-api-key"

# 启动（streamable-http）
python -m mcp_1panel --transport http --host 0.0.0.0 --port 8000

# 或 stdio 模式（Cursor 直连）
python -m mcp_1panel --transport stdio

客户端配置

mcphub

mcp_settings.json：

{
  "mcpServers": {
    "onepanel": {
      "type": "streamable-http",
      "url": "http://onepanel-mcp:8000/mcp"
    }
  }
}

Cursor / Windsurf / Claude Desktop

直连本 MCP（绕过 mcphub）：

{
  "mcpServers": {
    "1panel": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

环境变量

获取 1Panel API Key

1. 登录 1Panel 管理面板
2. 进入「面板设置」→「API 接口」
3. 开启 API 接口
4. 创建并复制 API Key
5. IP 白名单添加客户端 IP（测试可设 0.0.0.0/0）

工具命名与安全

命名规范

工具名统一 <模块>_<动作>：

• 读：container_search / website_list / database_mysql_list
• 写：container_start / website_create / app_install
• 高危：container_remove / website_delete

description 规范（mcphub 召回核心）

mcphub Smart Routing 是 pgvector 向量语义搜索，索引 name + description + parameters。description 质量直接决定召回率：

[模块] 一句话功能。读操作/⚠️写操作/⚠️高危。关键参数语义。

安全分层

开发

项目结构

mcp-1panel/
├── src/mcp_1panel/
│   ├── client.py          # 签名 HTTP 客户端（核心，MD5 签名）
│   ├── server.py          # FastMCP 实例与模块注册
│   ├── config.py          # 环境变量配置
│   ├── pagination.py      # 分页参数模型
│   ├── safety.py          # 读写安全分层
│   ├── errors.py          # 统一异常类型
│   └── tools/             # 业务模块（每个文件导出 register(mcp)）
│       ├── container.py / website.py / database.py ...
│       └── combos/        # 组合便捷接口（扩展点）
├── tests/                 # pytest + respx mock + FastMCP 端到端
├── references/openapi.json # 1Panel v2 API 权威数据源
├── docker-compose.yml     # mcphub + onepanel-mcp + postgres
└── Dockerfile             # 多阶段构建

新增工具

参考黄金范式 src/mcp_1panel/tools/container.py。一个工具约 15-25 行：

@mcp.tool()
async def module_action(
    param: Annotated[str, Field(description="参数说明")],
) -> dict:
    """[模块] 一句话功能。读操作。

    详细说明，对应 POST/GET /xxx/yyy。

    Args:
        param: 参数语义。
    """
    client = await get_client()
    return await client.post("/xxx/yyy", {"param": param})

测试

make test          # 全量测试
make test-cov      # 带覆盖率

测试用 respx mock httpx，不打真实 1Panel；用 FastMCP in-memory Client 端到端验证。

签名算法

1Panel v2 API 用 MD5 签名（见 client.py）：

Token = md5("1panel" + API_KEY + UnixTimestamp).hexdigest()
Header: 1Panel-Token = Token, 1Panel-Timestamp = 时间戳
URL: {endpoint}/api/v2{path}

关键点：

• 时间戳每请求重算（签名只在那一秒有效）
• 统一用 Python hashlib.md5（避免 shell md5 跨平台差异）
• v2 用 MD5 签名，绝不混 v1 明文 key

已知约束（踩坑）

• search 接口分页必填：page/pageSize/orderBy/order 全部必填，缺 orderBy 返回 400。client.search() 已自动注入默认值
• orderBy 可选值因模块而异：container 用 name/createdAt/state（驼峰），website 用 created_at/updated_at（下划线），实现时必须查 openapi.json 确认
• 反代真实后端：POST /websites/proxies body {"id": site_id} → data[].proxyPass（不要用 GET /websites/{id} 的 proxy 字段，那是创建快照）
• 生效域名：GET /websites/domains/{websiteId}（不要用 GET /websites/{id} 的 name 字段）

License

MIT