panelica-mcp

Panelica MCP 服务

使用通俗的英语与您的 Panelica 托管面板对话。 通过 Claude Desktop、Cursor、ChatGPT 或任何其他 Model Context Protocol 客户端配置域名、签发 SSL 证书、创建数据库或重启 服务。

404 个工具覆盖整个 External API 范围——账户、域名、DNS、 SSL、电子邮件、MySQL、FTP、安全、备份、服务资源等。

---

目录

• 工作原理
• 要求
• 安装
  • 选项 A — npm（推荐）
  • 选项 B — Docker
  • 选项 C — 从源代码构建
• 配置
  • 1. 开放 External API 端口
  • 2. 在面板中生成 API 密钥
  • 3. 使用 curl 验证凭据
• 接入 MCP 客户端
  • Claude Code（一条命令）
  • Claude Desktop
  • Cursor
  • OpenAI Codex CLI
  • Continue.dev、Cline、Zed
  • 通用 stdio 客户端
• 工具目录
• 会话示例
• 权限范围
• 安全模型
• 故障排除
• 开发
• 版本与支持
• 许可证

---

工作原理

+----------------+         stdio JSON-RPC          +-------------------+
|  MCP client    |  <----------------------------> |  panelica-mcp     |
|  (Claude, ...) |                                 |  (this package)   |
+----------------+                                 +---------+---------+
                                                             |
                                          HTTPS + HMAC-SHA256|
                                            X-API-Key        |
                                            X-Timestamp      |
                                            X-Signature      |
                                                             v
                              +------------------------------+------------------------------+
                              |  https://<panel-host>:8443/api/external/v1/...               |
                              |  nginx reverse proxy on the panel host                       |
                              |  (TLS termination + path rewrite: /api/external/X -> /X)     |
                              +------------------------------+------------------------------+
                                                             |
                                       127.0.0.1:3002 plain  |
                                                             v
                                            +----------------+-----------------+
                                            |  external-server (HMAC verify)   |
                                            +----------------+-----------------+
                                                             |
                                                             v
                                            +----------------+-----------------+
                                            |  Panelica panel + Linux services |
                                            +----------------------------------+

panelica-mcp 是一个轻量、无状态的适配器：

1. MCP 客户端通过 stdio 启动二进制文件。
2. 启动时，服务会从您的面板获取 <PANELICA_BASE_URL>/v1/api-spec，并据此生成工具列表（默认使用实时目录）。如果面板无法访问，则回退到捆绑的 tools/tools.json 快照。设置 PANELICA_LIVE_SPEC=0 可始终使用快照。
3. 客户端请求工具列表并接收列表，以及服务说明（介绍 ID、权限范围、响应封装、错误和速率限制的工作方式，以及工作流范例）；这些内容由同一目录生成。请参阅助手了解的内容。
4. 客户端调用工具时，服务会构建相应的 HTTP 请求，使用本地的 PANELICA_API_SECRET 通过 HMAC-SHA256 对请求签名，然后将其转发到面板。
5. HTTP 响应会作为工具结果返回给客户端。调用失败时，返回的是下一步操作说明（缺少权限范围、ID 错误、速率限制重置时间等），而不是单纯的状态码。

不会缓存任何数据，不会发送遥测信息，密钥也绝不会离开运行 MCP 服务的机器。

要求

• 运行中的 Panelica 面板（建议版本为 1.0.193 或更高；External API 接口从 1.0.180+ 起保持稳定）。
• 运行 panelica-mcp 的机器能够通过 HTTPS 访问面板 UI 的 8443 端口。这与您在浏览器中使用的端口相同——无需额外更改防火墙。
• 该机器上安装以下运行时之一：
  • Node.js ≥ 20，用于 npm 安装方式
  • Docker，用于容器方式

您无需在面板主机上安装任何内容，也无需将内部端口 3002 开放到公共互联网。

安装

选择适合您的 MCP 客户端配置的方式。三种方式生成的 stdio 二进制文件相同；请根据您偏好的沙箱模式选择。

选项 A — npm（推荐）

npm install -g panelica-mcp

或者无需安装即可运行（MCP 客户端会为您启动 npx）：

npx -y panelica-mcp

-y 标志会以非交互方式接受 npm 的“首次运行时安装”提示，这是 MCP 客户端所需的行为。

选项 B — Docker

每次发布时，都会将预构建镜像发布到 GitHub Container Registry：

docker pull ghcr.io/panelica/panelica-mcp:latest

从 MCP 客户端配置中运行：

{
  "command": "docker",
  "args": [
    "run", "--rm", "-i",
    "-e", "PANELICA_BASE_URL",
    "-e", "PANELICA_API_KEY",
    "-e", "PANELICA_API_SECRET",
    "ghcr.io/panelica/panelica-mcp:latest"
  ],
  "env": {
    "PANELICA_BASE_URL": "https://your-panel-host:8443/api/external",
    "PANELICA_API_KEY":  "pk_...",
    "PANELICA_API_SECRET": "sk_..."
  }
}

-i 会保持 stdin 连接，以便 MCP 客户端与容器通信。 --rm 会在客户端断开连接时移除容器。

选项 C — 从源代码构建

git clone https://github.com/Panelica/panelica-mcp.git
cd panelica-mcp
npm install
npm run build
node dist/index.js          # speaks MCP over stdio

要根据面板的实时 API 规范重新生成 tools/tools.json：

PANELICA_SPEC_URL="https://your-panel:8443/api/external/v1/api-spec" npm run rebuild-tools

配置

您需要三个值：可访问的基础 URL、API key 和 API secret。

1. 选择正确的基础 URL

Panelica 的 external-server 进程监听 127.0.0.1:3002，面板的 nginx 则通过 8443 将 /api/external/... 反向代理到该进程。nginx 会在转发前去掉 /api/external 前缀，因此，计算 HMAC 签名时使用的路径和后端收到的路径最终都会是 /v1/...——签名在整个链路上都能匹配，无需额外配置。

正确的 PANELICA_BASE_URL 取决于您在哪里运行 panelica-mcp：

场景	建议的 PANELICA_BASE_URL
MCP 客户端在您的笔记本电脑上，面板在远程服务上	https://<panel-host>:8443/api/external
MCP 客户端和面板在同一台机器上	http://127.0.0.1:3002

请勿将端口 3002 开放到公共互联网。默认安装会在所有接口上绑定该端口，但要求通过防火墙限制访问，或仅通过 8443 反向代理访问。

在您的机器上检查代理是否正常：

curl -sk https://<panel-host>:8443/api/external/health
# {"status":"ok"} or similar

如果出现 TLS 错误，这是因为面板使用了自签名证书——请在面板上安装真实证书（面板 UI → Settings → SSL），而不是在客户端禁用验证。

2. 在面板中生成 API key

1. 以 root 或拥有管理 API key 权限的账户登录面板。
2. 前往 Settings → API Keys → Generate API Key。
3. 选择您希望 MCP 服务拥有的权限范围。对于只读助手，*:read 即可（面板 1.0.528+；较旧版本需要单独的 <area>:read 权限范围）。如需全面自动化，还应授予 *:write 和 *:delete，或授予 *:*。此服务中每个工具的 description 都会列出它所需的权限范围。
4. 复制 key（格式类似 pk_...）和 secret（格式类似 sk_...）。secret 只会显示一次；请将其存储在密码管理器中。

3. 使用 curl 验证凭据

在配置 MCP 客户端之前，先确认凭据可以端到端正常工作：

export PANELICA_BASE_URL=https://your-panel-host:8443/api/external
export PANELICA_API_KEY=pk_xxxxxxxx
export PANELICA_API_SECRET=sk_xxxxxxxx

TS=$(date +%s)
# Signature is over METHOD + PATH + TIMESTAMP + BODY. The path is the
# backend-visible path (/v1/...) — NOT the /api/external/ prefix that nginx
# strips before forwarding. panelica-mcp does this automatically.
SIG=$(printf "GET/v1/api-keys${TS}" \
  | openssl dgst -sha256 -hmac "$PANELICA_API_SECRET" -hex | awk '{print $2}')

curl -sk "$PANELICA_BASE_URL/v1/api-keys" \
  -H "X-API-Key:   $PANELICA_API_KEY" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"

您应该会收到列出 API key 的 JSON。常见的 401 响应：

error.code	可能原因
MISSING_API_KEY / MISSING_TIMESTAMP / MISSING_SIGNATURE	请求头为空——请重新检查 curl 标志
INVALID_KEY_FORMAT	PANELICA_API_KEY 值格式错误
INVALID_TIMESTAMP	本地时钟偏差超过 5 分钟——请同步 NTP
INVALID_SIGNATURE	secret 错误，或者签名使用的路径包含 /api/external/（不应包含——nginx 会在后端收到请求前去掉此前缀）

4. 可选环境变量

变量	默认值	作用
PANELICA_TOOLSETS	core	直接注册哪些工具——参见工具集
PANELICA_LIVE_SPEC	1	启动时从你的面板 /v1/api-spec 构建目录；0 = 仅使用内置快照
PANELICA_SPEC_TIMEOUT_MS	8000	实时规范获取超时后回退到快照
PANELICA_TIMEOUT_MS	30000	每次调用的 HTTP 超时时间
PANELICA_MAX_RESULT_CHARS	60000	较大的列表结果会截断，只保留开头的条目，并附上 _truncated 说明，以免占满客户端上下文
PANELICA_STARTUP_PROBE	1	启动时调用一次 GET /v1/me，在说明中标明密钥的权限范围；设为 0 可跳过

将其接入 MCP 客户端

Claude Code（一个命令）

claude mcp add panelica \
  -e PANELICA_BASE_URL=https://your-panel:8443/api/external \
  -e PANELICA_API_KEY=pk_... \
  -e PANELICA_API_SECRET=sk_... \
  -- npx -y panelica-mcp

就这么简单——让 Claude Code“列出我的域名”或“为 example.com 创建数据库”，它就会通过权限受限的 API 密钥操作面板。

Claude Desktop

编辑 Claude Desktop 配置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Linux（Claude Desktop beta）： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "panelica": {
      "command": "npx",
      "args": ["-y", "panelica-mcp"],
      "env": {
        "PANELICA_BASE_URL":   "https://your-panel-host:8443/api/external",
        "PANELICA_API_KEY":    "pk_...",
        "PANELICA_API_SECRET": "sk_..."
      }
    }
  }
}

保存后，完全退出 Claude Desktop（不要只关闭窗口——请执行 Quit），然后重新打开。新聊天会显示 panelica 已连接为 MCP 服务，并提示“37 个工具可用”（核心集合加三个元工具；设置 PANELICA_TOOLSETS=all 可启用全部 488 个工具）。

Cursor

在 Settings → MCP → Add new server 中：

{
  "panelica": {
    "command": "npx",
    "args": ["-y", "panelica-mcp"],
    "env": {
      "PANELICA_BASE_URL":   "https://your-panel-host:8443/api/external",
      "PANELICA_API_KEY":    "pk_...",
      "PANELICA_API_SECRET": "sk_..."
    }
  }
}

OpenAI Codex CLI

添加到 ~/.codex/config.toml：

[mcp_servers.panelica]
command = "npx"
args = ["-y", "panelica-mcp"]

[mcp_servers.panelica.env]
PANELICA_BASE_URL = "https://your-panel:8443/api/external"
PANELICA_API_KEY = "pk_..."
PANELICA_API_SECRET = "sk_..."

Continue.dev、Cline、Zed

任何支持 MCP 且接受 stdio 命令的编辑器都可采用相同方式——提供 npx -y panelica-mcp（或构建后的 dist/index.js 的绝对路径）以及三个环境变量。

通用 stdio 客户端

PANELICA_BASE_URL=https://your-panel-host:8443/api/external \
PANELICA_API_KEY=pk_... \
PANELICA_API_SECRET=sk_... \
panelica-mcp

该进程通过 stdin/stdout 使用 MCP JSON-RPC 通信。首先发送 initialize 请求，然后发送 tools/list，最后发送 tools/call。

工具集——客户端可见内容

MCP 客户端会限制工具数量：Cursor 将所有服务的活动工具数限制在约 40 个，并会静默丢弃其余工具；而且每个已注册工具在每轮对话中都会消耗提示词 token。因此，服务默认注册精简的 核心 集合（34 个日常工具：账户、域名、DNS、SSL、数据库、电子邮件、FTP、备份、服务状态/服务、WordPress、Docker、套餐），以及三个可访问整个目录的元工具：

工具	功能
panelica_find_tools	按关键词搜索目录中的所有工具；返回名称、HTTP 路由、参数、请求体字段及各工具的返回内容
panelica_describe_tool	完整描述单个工具：列出每个参数及其来源、请求体字段（类型、是否必需）、响应封装结构及其数据字段
panelica_call	使用参数按名称运行目录中的任意工具（使用相同的受限权限、HMAC 签名客户端）

使用 PANELICA_TOOLSETS 选择工具集（逗号分隔，取并集）：

值	已注册工具
core（默认）	34 + 3 个元工具
all	目录中的所有工具 + 3 个元工具（0.3 之前的行为；适用于 Claude Code / Claude Desktop）
none	仅 3 个元工具
类别 slug，例如 domains,dns,ssl,git,docker,file_manager,laravel_apps,node_js_apps,python_apps,logs	这些类别（若包含 core，则也包含核心集合）

即使目录中的工具未注册，直接调用仍会被接受，因此客户端从 panelica_find_tools 获取工具名称后，可以通过任一方式调用。

助手了解的内容

只能看到 400 个工具名称的助手会猜测 ID、反复重试 403，并误读响应。panelica-mcp 让它像「熟记」API 一样了解 API。以下所有内容都由目录生成，因此它绝不会承诺面板上不存在的路径：

• 服务端指令（在 initialize 时发送，因此每个客户端都会将其注入模型上下文）：调用方式、每个 ID 都是通过列表调用获取的 UUID、用户称为账户、{"status":"success","data":…} 响应封装、未分页的列表、各类错误的含义及处理方法、权限范围类别、附带数量的类别映射、修改/破坏性工具的安全规则，以及仅在目录中包含所有步骤时才会纳入的工作流配方。
• 预先告知模型你的密钥。 启动时，服务端会调用一次 GET /v1/me，并告知模型它持有的密钥、权限范围、等级和到期时间——因此只读密钥会被声明为只读，超出权限范围的工具会告知需要添加的权限范围，而不会尝试调用。凭据遭拒时，会在首次工具调用前于指令中报告。（PANELICA_STARTUP_PROBE=0 可禁用此探测。）
• 权限范围与代码实际强制执行的规则一致。 较新的面板会根据中间件链推导所需权限范围，而不是依赖手写文档，其中包括「a、b 二者之一」规则和角色限制（ROOT/ADMIN）；工具描述会原样重复这些规则。
• 允许的值。 声明了取值列表的字段（ssl_provider、web_server、restart_policy 等）会带有 JSON Schema 的 enum 和 default，因此模型无需猜测。
• 大型列表仍然易于使用。 每个返回列表的 GET 都接受 _limit、_fields 和 _match；服务端会在响应中应用这些参数（面板不会看到它们），并报告 {total, matched, shown}，因此可以一次调用搜索包含 500 个域名的面板。
• 校验错误会指出字段名称。 Gin 校验失败会转换为 field "user_id" is required / field "type" must be one of the allowed values，并使用模型所用的 JSON 名称。
• 搜索能理解用户的语言。 panelica_find_tools 会将 website→domain、certificate→ssl、mailbox→email、container→docker，并处理复数词干，因此首次查询就能找到正确的工具。
• 自动处理短暂限制。 如果 429 的限流窗口会在 15 秒内重置，服务端会等待后重试一次；网络错误导致 GET 失败时会重试一次；如果与面板的时钟偏差超过两分钟，会在指令中标记（HMAC 时间戳可能会被拒绝）。
• 每个工具的描述都包含 HTTP 路由、所需权限范围、带有响应封装和首批数据字段的 Returns: 行，以及风险类别（只读 / 修改 / 破坏性）。
• ID 参数会说明其来源——UUID of the domain — obtain it from GET /v1/domains——路径、查询和请求体字段都一样。较新的面板会在规范中提供这些信息；对于较旧的面板，服务端会推导这些信息。
• panelica_describe_tool 会返回某个工具的确切参数、请求体字段和响应字段，以便模型在调用前进行检查。
• 错误会得到说明，而非原样回显：403 会指出缺少的权限范围，并说明重试无济于事；404 会提示重新列出并使用真实 ID；429 会报告重置窗口；5xx 会提示进行报告，而不是循环重试。原始面板响应会附加在后供参考。
• 限制结果大小：超大的列表响应会截断为前几个条目，并附带明确的 _truncated 说明（仍是有效 JSON），而不会让上下文被淹没。
• 面向支持这些功能的客户端提供资源：panelica://guide（指令）、panelica://catalogue（包含每个工具的路由和摘要），以及在实时模式下提供的 panelica://spec（你的面板完整 API 规范）。

响应字段列表来自面板的 /v1/api-spec；较新的面板会在构建时根据处理程序源代码生成该规范。早于此功能的面板仍可正常使用——其工具只会显示 {status, data}，不含字段名称。

工具目录

488 个工具根据面板实时提供的 /v1/api-spec 自动生成，因此始终与 API 保持同步。每个工具都带有 MCP 安全注释 （ 181 · 177 · 46）， 功能完备的客户端会利用这些注释自动批准读取操作，并在执行破坏性调用前发出警告。 请求体字段和查询参数均根据面板处理程序代码生成 （面板代码库中的 gen-external-schemas），因此在 1.0.528 及更高版本的面板上， 变更类工具会带有类型化且标记为必填的请求体，而 …/suspend 或 …/restart 等操作端点则会声明无需请求体。

类别	工具数
Git	43
域名	32
日志	26
文件管理器	23
Laravel 应用	21
Python 应用	19
Node.js 应用	18
账户	16
CloudFlare	12
Docker	12
IP 地址	9
Cron 作业	8
电子邮件	8
FTP	8
安全	8
数据库	7
垃圾邮件	7
SSH 用户	7
WordPress	7
API 密钥	6
许可证	6
MySQL 用户	6
服务	6
Webhook	6
备份	5
DNS	5
迁移	5
套餐	5
快照	5
2FA	4
防病毒	4
备份计划	4
邮件列表	4
SSL	4
带宽	3
配置锁	3
核心	3
远程 MySQL	3
会话	3
子域名	3
终端	3
审计	2
指标	2
通知	2
面板设置	2
资源配额	2
SMTP 中继	2
系统 Cron	2
邮件队列	1
PHP	1
重定向	1

机器可读的完整列表：tools/tools.json。

会话示例

连接好服务后，可以在 MCP 客户端中尝试以下操作：

配置域名。

“在 starter 套餐下为 [email protected] 创建一个新账户，然后 为其添加域名 alice-shop.com，并签发 Let's Encrypt 证书。”

助手会从目录中选取 panelica_accounts_post_v1_accounts、 panelica_domains_post_v1_domains 和 panelica_ssl_post_v1_ssl_...， 根据对话填写参数，并依次调用它们。你可以在客户端的工具日志中查看调用过程。

诊断。

“显示 alice-shop.com 过去 24 小时的带宽用量，并告诉我 本月用量是否可能超过套餐配额。”

批量清理。

“列出所有 SSL 证书将在未来 14 天内到期的域名，并 全部续期。”

DNS 迁移。

“对于区域 alice-shop.com，列出当前的 A 和 CNAME 记录，然后 添加一条指向 alice-shop.com 的 www CNAME 记录，以及一条指向 203.0.113.10 的 mail A 记录。”

助手只会调用 API 密钥已获授权范围内的工具，因此只读密钥可以安全地回答“列出”类问题，但会拒绝“创建 / 删除”操作。

权限范围

API 密钥具有范围限制 — 仅授予 AI 助手所需的访问权限，不多给。在面板中创建密钥时，不会预先选中任何范围，创建对话框支持对全部 50 个范围进行实时搜索。 仅查看 / 列表 · 创建 / 更新 · 删除 · 特殊访问权限。 每个类别也支持通配符（domains:*），而 *:* 则授予所有权限。

区域	权限范围
账户	accounts:read · accounts:write · accounts:delete
域名和子域名	domains:read · domains:write · domains:delete
数据库	databases:read · databases:write · databases:delete
DNS	dns:read · dns:write · dns:delete
电子邮件	email:read · email:write · email:delete
FTP	ftp:read · ftp:write · ftp:delete
SSL	ssl:read · ssl:write
备份和快照	backups:read · backups:write · backups:restore
文件管理器	files:read · files:write · files:delete
CloudFlare	cloudflare:read · cloudflare:write · cloudflare:delete
Docker 和应用模板	docker:read · docker:write · docker:delete
应用托管（Laravel / Node.js / Python）	apps:read · apps:write · apps:delete
Git 和部署	git:read · git:write · git:delete
日志和审计	logs:read · logs:write
安全（防病毒、防火墙、IP 封禁）	security:read · security:write · security:delete
服务和基础设施	server:read · server:write
服务控制	services:restart · services:start · services:stop
套餐	plans:read · plans:write
Webhook	webhooks:read · webhooks:write · webhooks:delete
带宽	bandwidth:read
许可证	license:read
迁移（面板到面板）	migrations:read
终端	terminal:access
完全访问	*:*
修改服务控制需要专用的操作作用域（或
server:write）——仅有指标读取权限的 server:read 密钥无法停止 MySQL。

速率限制

API 密钥带有速率限制等级（创建密钥时的 rate_limit_tier： starter 每分钟 60 次，professional 每分钟 300 次，business 每分钟 1000 次，enterprise 不受限制）。默认的 starter 等级很容易在助手发起大量并行调用时耗尽；如果看到 429 RATE_LIMIT_EXCEEDED（响应中包含 reset_at），请为助手创建等级更高的密钥。

安全模型

• HMAC-SHA256 请求签名。 每个请求都使用 API 密钥对 METHOD + PATH + QUERY + TIMESTAMP + BODY 进行签名。面板会拒绝时间戳与服务器时钟相差超过 5 分钟的请求，因此无法重放请求。
• 密钥保留在本地。 API 密钥从进程环境中读取，仅用于计算签名。它绝不会被记录日志、发送给任何第三方或写入磁盘。
• 受作用域限制的密钥。 每种用例生成一个 API 密钥。仅授予该用例所需的作用域——例如，为只读助手授予 domains:read，仅在需要完全自动化时授予 *:write。
• 审计跟踪。 每个请求都会记录在面板的常规审计日志中，并受 RBAC 控制。通过 MCP 执行的操作与其他经过身份验证的 API 调用无法区分，并且可以追溯到执行操作的 API 密钥。
• 不收集数据。 此服务不发送遥测数据、不写入缓存，也不会联系任何第三方。
• 容器加固。 Docker 镜像以非 root 用户运行，且不暴露任何端口——它仅通过 stdio 通信。

故障排除

症状	可能原因	解决方法
客户端报告“0 个可用工具”	服务在启动时崩溃——通常是缺少环境变量	在设置好三个环境变量的 shell 中运行一次 panelica-mcp；查看 stderr
401 MISSING_API_KEY	未设置 PANELICA_API_KEY，或请求头透传配置错误	重新检查 MCP 客户端配置；编辑后重启客户端
401 INVALID_SIGNATURE	PANELICA_API_SECRET 错误，或时钟偏差超过 5 分钟	在 MCP 主机和面板主机上运行 chronyc tracking（或 timedatectl status）
401 INVALID_TIMESTAMP	本地时钟偏差超过 5 分钟	在 MCP 主机上同步 NTP
连接 BASE_URL 超时	主机或端口错误——通常是 URL 中漏掉了 :8443/api/external	使用 curl -sk $PANELICA_BASE_URL/health 验证——应返回 {"status":"ok"}
工具结果以 Panelica API error 403 开头，并指出某个作用域	API 密钥缺少该作用域	在面板中为密钥添加该作用域（Settings → API Keys）；系统会提示助手不要重试
工具结果显示 Panelica API error 404 … re-list	助手使用的 ID 不属于此密钥所有者	无需在服务端修复；相关指引会让助手重新列出项目并选择有效的 ID
工具描述显示“Schema not statically declared”	该端点绑定了动态请求正文（map / multipart）	传入自由格式的 body 对象；面板会进行验证，并在缺少字段时返回 400，且会提示助手读取错误信息
启动日志显示 clock skew of Ns versus the panel	MCP 主机时钟不准	在 MCP 主机上同步 NTP；签名请求会携带面板检查的时间戳
启动日志显示 startup credential check failed	GET /v1/me 拒绝了密钥或密钥密码	相关说明已告知助手；请在面板中修正密钥并重启客户端
TLS 验证失败	面板使用的是自签名证书	如果 MCP 主机信任该 CA，则无需额外配置即可正常工作。否则，请在面板上部署有效证书（panel UI → Settings → SSL）——不要在客户端禁用 TLS 验证

如果问题仍未解决，请在 github.com/Panelica/panelica-mcp/issues 提交 issue，并附上（已删去敏感信息的）stderr 输出。

开发

git clone https://github.com/Panelica/panelica-mcp.git
cd panelica-mcp
npm install
npm run build
node dist/index.js

项目结构：

.
├── src/index.ts          # MCP server (stdio transport, HMAC client, live-spec loader)
├── src/catalog.ts        # spec → tools generator (shared by runtime and build script)
├── src/toolsets.ts       # core set, PANELICA_TOOLSETS selection, find/describe/call meta tools
├── src/instructions.ts   # server instructions generated from the catalogue
├── src/errors.ts         # error explanations + result bounding
├── tools/
│   ├── build-tools.mjs   # Generates tools.json from the API spec
│   ├── api-spec.json     # Committed snapshot of the live /v1/api-spec
│   └── tools.json        # tool definitions, auto-generated (committed)
├── .github/workflows/
│   └── refresh-tools.yml # Weekly CI: regenerate, bump, tag, publish npm + Docker + Registry
├── Dockerfile
├── smithery.yaml         # Smithery deployment manifest
├── .env.example
└── README.md

保持工具目录更新

目录不会因手动维护而与 API 脱节。后端提供始终最新的 /v1/api-spec（由其路由注册表构建），工具会根据它重新生成：

# Rebuild from the committed snapshot (offline):
npm run rebuild-tools

# Pull the live spec, refresh the snapshot, and rebuild:
PANELICA_SPEC_URL="https://your-panel:8443/api/external/v1/api-spec" npm run rebuild-tools

CI（refresh-tools.yml）每周针对 PANELICA_SPEC_URL 仓库机密中指定的面板运行此流程。目录有变更时，流程会递增补丁版本、创建标签，并在同一次运行中发布到 npm、Docker 镜像和 MCP Registry 条目，因此新的 API 端点会自动提供给 npx -y panelica-mcp 用户。正在运行的服务甚至不需要这样做：使用默认的实时目录时，它们会从所连接的面板读取规范。每个工具都带有安全注释（GET 使用 readOnlyHint，DELETE 使用 destructiveHint），支持这些注释的 MCP 客户端会据此自动批准读取操作，并在破坏性调用前发出警告。

另有一份独立的内部数据集，包含面板的所有端点（共 1,263 个），仅用于训练——此软件包只公开有文档记录的 404 个外部 API 端点。内部面板端点、记录的 DEV 数据和训练用 jsonl 文件均不属于公共代码库。

版本管理与支持

• 此软件包遵循 Panelica 面板的 External API。只有当面板本身发布不向后兼容的 API 变更时，工具签名才会变更；届时软件包的主版本号也会相应递增。
• 重新生成 tools/tools.json 并发布版本后，新端点即可使用；或者在实时模式下，立即从你自己的面板 /v1/api-spec 获取。
• 响应字段列表、ID 来源和清理后的描述均来自面板规范；不包含这些信息的旧版面板仍可使用功能较简单的工具。
• 面板问题（API 本身，而非此客户端）：请访问 Panelica 论坛：forum.panelica.com。
• 客户端 / 打包问题： github.com/Panelica/panelica-mcp/issues。

许可证

MIT。请参阅 LICENSE。

链接

• 面板网站：https://panelica.com
• 在线演示：https://demo.panelica.com
• 文档：https://panelica.com/docs
• 论坛与支持：https://forum.panelica.com
• 公共安装程序：https://latest.panelica.com/install.sh