1panel-api

1Panel API Skills

🎯 Manage 1Panel with tool calls instead of having the Agent hastily assemble curl.

This repository contains 1Panel API documentation and a zero-dependency Node.js tool layer:

• tools/1panel-tool.js: command-line / JSON tool-call runner
• tools/1panel-mcp.js: MCP stdio server, exposing tools to Agents that support MCP
• tools/1panel-lib.js: Token calculation, API requests, endpoint index parsing
• docs/SKILL-*.md: 1Panel API endpoint documentation organized by module

Quick Start

1. Prepare Node.js

Node.js 18+ is required, because the tool uses the built-in fetch, so no npm dependencies need to be installed.

node --version

2. Configure 1Panel connection information

For first-time use, please provide or set the following information:

Information	Environment Variable	Description	Example
1Panel address	ONEPANEL_BASE_URL	Server IP/domain + panel port	http://192.168.1.100:8888
API Key	ONEPANEL_API_KEY	Generated in the panel under "Settings" -> "API Keys"	xxxxxxxx
Allow self-signed HTTPS	ONEPANEL_INSECURE	Can be set to true	true

export ONEPANEL_BASE_URL='http://你的地址:8888'
export ONEPANEL_API_KEY='你的 API Key'

3. Get API Key

1. Log in to the 1Panel panel
2. Go to "Settings" -> "API Keys"
3. Click "Create" to generate a new key
4. Copy the generated key to ONEPANEL_API_KEY

Agent Usage Rules

When an Agent uses this Skill to manage 1Panel:

1. Prefer using Node tool / MCP tool, do not hand-write curl。
2. When unsure of the API path, first call onepanel_endpoint_search to search for endpoints.
3. After confirming the API, then call onepanel_get、onepanel_post or onepanel_request。
4. For dangerous operations such as deletion, stopping services, restarting services, overwriting configurations, and cleaning up files, first confirm the scope of impact with the user.
5. When returning to the user, explain which tool was called, which endpoint, the status code, and the key results.

MCP tools

tools/1panel-mcp.js exposes the following tools:

Tool	Purpose
onepanel_endpoint_search	Search the built-in 1Panel API endpoint index in this repository
onepanel_modules	List built-in API modules
onepanel_get	GET a 1Panel API endpoint
onepanel_post	POST a 1Panel API endpoint
onepanel_request	Call a 1Panel API endpoint with any method

MCP Configuration Example

Add the following configuration to the configuration of an Agent that supports MCP:

{
  "mcpServers": {
    "1panel": {
      "command": "node",
      "args": ["/absolute/path/to/1Panel-Skills/tools/1panel-mcp.js"],
      "env": {
        "ONEPANEL_BASE_URL": "http://你的地址:8888",
        "ONEPANEL_API_KEY": "你的 API Key"
      }
    }
  }
}

If using Hermes Agent, you can use:

hermes mcp add 1panel --command "node /absolute/path/to/1Panel-Skills/tools/1panel-mcp.js"

Then set ONEPANEL_BASE_URL and ONEPANEL_API_KEYin Hermes's environment variables. After restarting the session, the MCP tools can be used.

CLI / JSON tool-call Usage

Search endpoints

node tools/1panel-tool.js endpoints --keyword container --limit 5

Query modules

node tools/1panel-tool.js modules

GET request

node tools/1panel-tool.js get /containers/status

POST request

node tools/1panel-tool.js post /containers/search \
  --body '{"page":1,"pageSize":20}'

Generic request

node tools/1panel-tool.js request \
  --method GET \
  --path /containers/status

JSON tool-call mode

node tools/1panel-tool.js tool-call '{
  "tool": "onepanel_request",
  "args": {
    "method": "GET",
    "path": "/containers/status"
  }
}'

The return value is uniformly JSON, containing:

{
  "ok": true,
  "status": 200,
  "statusText": "OK",
  "url": "http://example:8888/api/v2/containers/status",
  "data": {}
}

Authentication Implementation

The Node tool automatically completes 1Panel API authentication internally, so the Agent does not need to manually calculate tokens.

Authentication logic:

timestamp = 当前 Unix 秒级时间戳
token = md5("1panel" + apiKey + timestamp)
headers:
  1Panel-Token: token
  1Panel-Timestamp: timestamp
  Content-Type: application/json

Feature Modules

Module	Description
Apps	App store, installed app management
Websites	Website creation, configuration, reverse proxy, SSL
Containers	Docker container management
Databases	MySQL、PostgreSQL、Redis、MongoDB
Files	File upload, download, compression, decompression
Backups	Backup and restore
Cronjobs	Scheduled tasks
Runtimes	PHP, Node, Python, Go, Java runtime environments
Hosts	Host monitoring, firewall, SSH, disk management
Settings	System configuration, user management

For the complete endpoint index, see INDEX.md, for detailed API documentation, see docs directory.

Common workflows

Check Docker / container status

1. Search endpoints:onepanel_endpoint_search({"keyword":"containers status"})
2. Call:onepanel_get({"path":"/containers/status"})
3. Report the results based on the returned container count, image count, and network count.

Paginated container query

Call:

{
  "tool": "onepanel_post",
  "args": {
    "path": "/containers/search",
    "body": {"page": 1, "pageSize": 20}
  }
}

Call an unknown interface

1. Use onepanel_endpoint_search to look up paths by keyword or module.
2. Read the parameter table in the corresponding docs/SKILL-*.md .
3. Use onepanel_request to pass method、path、query、body。

Validation

npm test

This command checks the Node file syntax and confirms that the endpoint index can be parsed normally from docs/ .