MCP Servers

_{Released under GPL-3.0 · Forged in Go · Born for the AI age}

+ "Don't click. Don't type commands. Just describe what you want."
- A new paradigm for server administration — conversational, intentional, magical.

  Built With

🏗️   How It Works

一句话：MCP Go SDK 把每个工具暴露给 AI，工具内部用 HTTP 客户端调用 1Panel REST API。

  ┌──────────────────────┐
  │   AI 助手 (Claude /   │
  │   Windsurf / Cursor)  │
  └──────────┬────────────┘
             │ MCP 协议 (JSON-RPC)
             │ stdio / sse / streamable-http
  ┌──────────▼────────────┐
  │   mcp-1panel-full     │  ← 你正在看的项目
  │  (Go binary, 90+ 工具) │
  └──┬─────────────┬──────┘
     │             │
     │ HTTP API    │ SSH / Shell / FS
     │             │
  ┌──▼──────┐  ┌──▼──────────┐
  │ 1Panel  │  │ 远程主机 /   │
  │ Server  │  │ 本地系统     │
  └─────────┘  └─────────────┘

🧪 单个工具的内部结构（以 stop_process 为例）

// 1. 定义输入类型 — jsonschema tag 自动生成 AI 可读的 schema
type StopProcessInput struct {
    PID int `json:"PID" jsonschema:"process ID to stop/kill"`
}

// 2. 注册为 MCP 工具
var StopProcessTool = mcp.NewServerTool[StopProcessInput, any](
    "stop_process",
    "[DANGEROUS] Kill/stop a running process by PID",
    func(ctx context.Context, _ *mcp.ServerSession, params *mcp.CallToolParamsFor[StopProcessInput]) (*mcp.CallToolResultFor[any], error) {
        // 3. 调用 1Panel REST API
        client := utils.NewPanelClient("POST", "/process/stop",
            utils.WithPayload(map[string]interface{}{"PID": params.Arguments.PID}))
        var result interface{}
        return client.Request(&result)
    },
)

每个工具都遵循三段式：Input 类型 → MCP 注册 → HTTP 调用，结构清晰可复用。

🌐 三种传输模式适用场景

| 模式 | 适用场景 | 性能 | |---|---|---| | stdio | 本地 MCP 客户端（Claude Desktop / Windsurf / Cursor） | ⚡⚡⚡ 最快，零网络开销 | | sse | 浏览器或老式 HTTP 客户端 | ⚡⚡ 单向流推送 | | streamable-http | 现代远程客户端（推荐） | ⚡⚡⚡ 双向 HTTP 流 |

  Tool Catalog

⚡   Quick Start

1️⃣ Build from source

git clone https://github.com/Aurora100729/mcp-1panel-full.git
cd mcp-1panel-full
go build -o mcp-1panel-full .

Requires Go 1.25+.

2️⃣ Get a 1Panel API key

1Panel  →  Profile (top-right)  →  API Interface  →  Enable
        →  Copy Key  →  Add your client IP to whitelist ⚠️

3️⃣ Run

# stdio (default — for MCP clients)
./mcp-1panel-full --token YOUR_API_KEY --host http://127.0.0.1:9999

# Streamable HTTP (recommended for HTTP)
./mcp-1panel-full --transport streamable-http --addr 0.0.0.0:8000 \
  --token YOUR_API_KEY --host http://127.0.0.1:9999

# SSE (legacy HTTP)
./mcp-1panel-full --transport sse --addr 0.0.0.0:8000 \
  --token YOUR_API_KEY --host http://127.0.0.1:9999

4️⃣ Or run with Docker

docker build -t mcp-1panel-full .

docker run -d --name mcp-1panel \
  -p 8000:8000 \
  mcp-1panel-full \
  --transport streamable-http --addr 0.0.0.0:8000 \
  --token YOUR_API_KEY \
  --host http://host.docker.internal:9999

🎛️ CLI Flags

_{💡 Pre-fill SSH defaults so AI calls only need command.}

🔌 MCP Client Config

{
  "mcpServers": {
    "mcp-1panel-full": {
      "command": "C:\\path\\to\\mcp-1panel-full.exe",
      "args": [
        "--token", "YOUR_API_KEY",
        "--host", "http://127.0.0.1:9999",
        "--ssh-host", "your.server.ip",
        "--ssh-user", "ubuntu",
        "--ssh-key", "C:\\Users\\You\\.ssh\\id_rsa",
        "--ssh-port", "22"
      ]
    }
  }
}

{
  "mcpServers": {
    "mcp-1panel-full": {
      "command": "/usr/local/bin/mcp-1panel-full",
      "args": [
        "--token", "YOUR_API_KEY",
        "--host", "http://127.0.0.1:9999"
      ]
    }
  }
}

  SSH Remote Execution

The crown jewel of this server — a single tool that lets your AI run anything on remote hosts.

{
  "host": "1.2.3.4",
  "user": "ubuntu",
  "keyPath": "/path/to/id_rsa",
  "command": "df -h"
}

{ "command": "df -h" }

📤 Output format

exit=0
--- stdout ---
ubuntu
VM-0-5-ubuntu

--- stderr ---

Plus structured JSON: { host, user, port, command, stdout, stderr, exitCode }.

💬   Real-World Conversations

Watch how natural language unfolds into precise tool calls.

AI ➜ get_dashboard_info()
↳ CPU 5%, Mem 6%, Disk 12%, Uptime 2:03

AI ➜ app_store_list("redis")
AI ➜ panel_request POST /apps/install
       { name: "redis", port: 6380, ... }

AI ➜ list_databases() → 5 dbs
AI ➜ database_backup × 5 in parallel

AI ➜ create_firewall_ip_rule(
       address: "1.2.3.4",
       strategy: "drop"
     )

AI ➜ list_installed_apps() → openresty
AI ➜ app_installed_detail(id)
AI ➜ container_logs(id, tail=100)

AI ➜ ssh_remote_exec(
       command: "find /tmp -size +100M -delete"
     )

🗂️ Project Layout

mcp-1panel-full/
│
├── 🚪 main.go                       # Entry · CLI flags · tool registration
├── 📦 utils/                        # HTTP client · helpers
│
├── 🛠️  operations/                  # 1Panel API tools — domain-grouped
│   ├── 🌐 generic/                  #   panel_request passthrough
│   ├── 📊 system/                   #   System / Dashboard
│   ├── 🌍 website/                  #   Sites
│   ├── 🔐 ssl/                      #   SSL certificates
│   ├── 🛍️  app/                     #   App store
│   ├── 💾 database/                 #   MySQL · PostgreSQL · Redis
│   ├── 🐳 container/                #   Docker · Compose
│   ├── 📁 file/                     #   File management
│   ├── 🛡️  firewall/                #   Firewall rules
│   ├── ⏰ cron/                     #   Scheduled jobs
│   ├── 🔧 process/                  #   Process management
│   ├── 🔑 sshmanage/                #   SSH service + remote exec ⭐
│   ├── 📝 panellog/                 #   Audit logs
│   ├── 📈 monitor/                  #   Performance monitoring
│   ├── 💼 backup/                   #   Backup / restore
│   ├── 📷 snapshot/                 #   System snapshots
│   ├── ⚙️  setting/                 #   System settings
│   ├── 🧪 toolbox/                  #   DNS · Hosts · Swap · Fail2Ban
│   ├── 🌱 runtime/                  #   PHP / Node / Python runtimes
│   └── 📐 types/                    #   Shared types
│
├── 🧰 tools/                        # Local capability tools
│   ├── 💻 shell/                    #   Local shell exec
│   └── 📂 localfs/                  #   Local filesystem
│
├── 📋 logs/                         # Runtime logs (auto-created)
├── 🐳 Dockerfile
├── 📦 go.mod
└── 📖 README.md                     # ← you are here

🩺 Troubleshooting

🛡️ Security

⚠️ This tool grants total control — full 1Panel admin + remote SSH exec + local shell. Treat it like root credentials.

Must do

• 🚫 Never run in untrusted or public environments
• 🚫 Never commit tokens / private keys (already gitignored: *.pem *.key)
• 🚫 Avoid --ssh-password in plain config files — use keys
• ⚠️ Confirm [DANGEROUS] tagged tools before executing

Should do

• 🔐 Store private keys at ~/.ssh/ with chmod 600
• 🔐 Use a dedicated 1Panel API key with IP allow-listing
• 🔄 Rotate API keys + SSH keys regularly
• 📜 Use read-only credentials for production where possible

📜 Changelog

💎 Acknowledgements

1Panel Modern Linux panel

mcp-1panel Original MCP server

MCP The protocol

x/crypto/ssh SSH client for Go

📄 License

Released under GNU General Public License v3.0 — see LICENSE.

Any modification, redistribution or derivative work must remain open under the same license and preserve copyright.

⭐   Star History

_{If this project saved you a click — give it a ⭐}

@@  Conversations > Commands.  Intent > Syntax.  AI > Toil.  @@
+ Built with care · Open to all · Made for the curious