Content
<div align="center">
<!-- ═══════════════════════════════ HERO ═══════════════════════════════ -->
<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=0:1a1a2e,50:16213e,100:0f3460&height=280§ion=header&text=mcp-1panel-full&fontSize=78&fontColor=ffffff&animation=fadeIn&fontAlignY=38&desc=AI-Native%20Server%20Management%20%E2%80%A2%2090%2B%20Tools%20%E2%80%A2%20Built%20with%20Go&descAlignY=58&descSize=18" />
<!-- ════════════════════════════ TYPING TAGLINE ════════════════════════ -->
<a href="https://github.com/Aurora100729/mcp-1panel-full">
<img src="https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=600&size=20&pause=1200&color=58A6FF¢er=true&vCenter=true&width=820&lines=Talk+to+your+server+in+plain+English.;90%2B+tools+%E2%80%A2+Full+1Panel+v2+API+%E2%80%A2+SSH+%E2%80%A2+Docker+%E2%80%A2+Files;Built+for+Claude+%C2%B7+Windsurf+%C2%B7+Cursor+%C2%B7+Any+MCP+client" />
</a>
<br/>
<!-- ════════════════════════════ CORE BADGES ═══════════════════════════ -->
<p>
<img src="https://img.shields.io/badge/Go-1.25-00ADD8?style=for-the-badge&logo=go&logoColor=white&labelColor=0D1117" />
<img src="https://img.shields.io/badge/MCP-1.0-512BD4?style=for-the-badge&logo=anthropic&logoColor=white&labelColor=0D1117" />
<img src="https://img.shields.io/badge/License-GPL%20v3-3DA639?style=for-the-badge&logo=gnu&logoColor=white&labelColor=0D1117" />
<img src="https://img.shields.io/badge/Tools-90%2B-FF6B6B?style=for-the-badge&logo=toolbox&logoColor=white&labelColor=0D1117" />
<img src="https://img.shields.io/badge/1Panel-v2.0-005CFF?style=for-the-badge&logo=server&logoColor=white&labelColor=0D1117" />
</p>
<!-- ════════════════════════════ STATUS BADGES ══════════════════════════ -->
<p>
<img src="https://img.shields.io/github/stars/Aurora100729/mcp-1panel-full?style=flat-square&color=FFD700&labelColor=0D1117&label=%E2%9C%A6%20stars" />
<img src="https://img.shields.io/github/forks/Aurora100729/mcp-1panel-full?style=flat-square&color=58A6FF&labelColor=0D1117&label=%E2%88%9E%20forks" />
<img src="https://img.shields.io/github/issues/Aurora100729/mcp-1panel-full?style=flat-square&color=FF6B6B&labelColor=0D1117&label=%E2%9C%97%20issues" />
<img src="https://img.shields.io/github/last-commit/Aurora100729/mcp-1panel-full?style=flat-square&color=00C896&labelColor=0D1117&label=%E2%9C%93%20last%20commit" />
<img src="https://img.shields.io/github/repo-size/Aurora100729/mcp-1panel-full?style=flat-square&color=B57EDC&labelColor=0D1117&label=%E2%80%BB%20size" />
</p>
<sub><i>Released under GPL-3.0 · Forged in Go · Born for the AI age</i></sub>
</div>
<!-- ════════════════════════ ANIMATED RAINBOW LINE ════════════════════════ -->
<img src="https://user-images.githubusercontent.com/74038190/212284100-561aa473-3905-4a80-b561-0d28506553ee.gif" width="100%" height="3"/>
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
TAGLINE / MANIFESTO BLOCK
═══════════════════════════════════════════════════════════════════ -->
<div align="center">
<img src="https://user-images.githubusercontent.com/74038190/212750147-854a394f-fee9-4080-9770-78a4b7ece53f.gif" width="60" />
```diff
+ "Don't click. Don't type commands. Just describe what you want."
- A new paradigm for server administration — conversational, intentional, magical.
```
<a href="https://github.com/Aurora100729/mcp-1panel-full">
<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=500&size=16&pause=1000&color=B57EDC¢er=true&vCenter=true&width=600&lines=%E2%9C%A6+conversational+%E2%80%A2+intentional+%E2%80%A2+magical+%E2%9C%A6" />
</a>
</div>
<br/>
<img src="https://user-images.githubusercontent.com/74038190/212284100-561aa473-3905-4a80-b561-0d28506553ee.gif" width="100%" height="3"/>
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
QUICK PITCH
═══════════════════════════════════════════════════════════════════ -->
<table>
<tr>
<td valign="top" width="50%">
### 💡 Why this exists
Traditional server management means juggling SSH terminals, browser tabs, doc pages, and command-line cheat sheets — every single day.
**`mcp-1panel-full`** unfolds the entire 1Panel API surface into a vocabulary your AI assistant can speak natively. From spinning up containers to renewing SSL certificates to chasing down errant processes, you describe; the AI executes.
> *Make infrastructure feel like a conversation.*
</td>
<td valign="top" width="50%">
### 🌟 What's inside
- 📦 **90+ tools** — full 1Panel v2 surface
- 🔧 **`panel_request`** — escape hatch for any future endpoint
- 🔒 **Native SSH** — password / key / passphrase / kbd-interactive
- ⚙️ **Sticky defaults** — set once via CLI flags, call with `command` only
- 🌊 **Three transports** — `stdio` / `sse` / `streamable-http`
- 🐳 **Docker-friendly** — one-line container deploy
- 🛡️ **Structured output** — JSON for AI second-pass reasoning
- 🩹 **v2.0.15 compatibility patches** — applied upstream-first
</td>
</tr>
</table>
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
TECH STACK
═══════════════════════════════════════════════════════════════════ -->
<h2 align="center">
<img src="https://user-images.githubusercontent.com/74038190/216655822-0c750cf3-21f9-4ac5-869b-ec3e6b1a72d6.gif" width="32" /> Built With
</h2>
<div align="center">
<img src="https://skillicons.dev/icons?i=go,docker,linux,nginx,redis,mysql,postgres,bash&perline=8" />
<br/><br/>
<img src="https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=400&size=14&pause=1000&color=8B949E¢er=true&vCenter=true&width=600&lines=The+languages+and+infrastructure+this+project+speaks+fluently." />
</div>
<br/>
<img src="https://user-images.githubusercontent.com/74038190/212284100-561aa473-3905-4a80-b561-0d28506553ee.gif" width="100%" height="3"/>
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
TABLE OF CONTENTS
═══════════════════════════════════════════════════════════════════ -->
<div align="center">
<h2>📖 Compass</h2>
<a href="#-how-it-works">How It Works</a> ·
<a href="#-tool-catalog">Tool Catalog</a> ·
<a href="#-quick-start">Quick Start</a> ·
<a href="#-cli-flags">CLI Flags</a> ·
<a href="#-mcp-client-config">MCP Config</a> ·
<a href="#-ssh-remote-execution">SSH Remote</a> ·
<a href="#-real-world-conversations">Examples</a><br/>
<a href="#-project-layout">Layout</a> ·
<a href="#-troubleshooting">Troubleshooting</a> ·
<a href="#-security">Security</a> ·
<a href="#-changelog">Changelog</a>
</div>
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
HOW IT WORKS
═══════════════════════════════════════════════════════════════════ -->
<h2>
🏗️ How It Works
</h2>
> In one sentence: **MCP Go SDK exposes each tool to AI, and tools internally use HTTP client to call 1Panel REST API**.
<table>
<tr>
<td valign="top" width="50%">
#### 🧬 Architecture in 30 seconds
```
┌──────────────────────┐
│ AI Assistant (Claude / │
│ Windsurf / Cursor) │
└──────────┬────────────┘
│ MCP Protocol (JSON-RPC)
│ stdio / sse / streamable-http
┌──────────▼────────────┐
│ mcp-1panel-full │ ← The project you're looking at
│ (Go binary, 90+ tools) │
└──┬─────────────┬──────┘
│ │
│ HTTP API │ SSH / Shell / FS
│ │
┌──▼──────┐ ┌──▼──────────┐
│ 1Panel │ │ Remote Host / │
│ Server │ │ Local System │
└─────────┘ └─────────────┘
```
</td>
<td valign="top" width="50%">
#### 🛠️ Tech Foundation
| Component | Technology |
|---|---|
| Language | **Go 1.25** — Statically compiled, zero-dependency deployment |
| MCP Implementation | [`modelcontextprotocol/go-sdk`](https://github.com/modelcontextprotocol/go-sdk) |
| HTTP Client | `net/http` + custom `utils.PanelClient` |
| SSH | [`golang.org/x/crypto/ssh`](https://pkg.go.dev/golang.org/x/crypto/ssh) — Supports password / private key / passphrase / kbd-interactive |
| Type System | [`jsonschema`](https://json-schema.org/) tag auto-generation tool schema |
| Transport Layer | stdio · SSE · streamable-http triple-mode switchable |
| Containerization | Multi-stage Dockerfile, final image < 20 MB |
</td>
</tr>
</table>
#### Internal Structure of a Single Tool (using `stop_process` as an example)
```go
// 1. Define input type — jsonschema tag automatically generates AI-readable schema
type StopProcessInput struct {
PID int `json:"PID" jsonschema:"process ID to stop/kill"`
}
// 2. Register as an MCP tool
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. Call 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)
},
)
```
Each tool follows a three-part structure: **`Input Type` → `MCP Registration` → `HTTP Call`**, with a clear and reusable structure.
#### Applicable Scenarios for Three Transmission Modes
| Mode | Applicable Scenarios | Performance |
|---|---|---|
| **`stdio`** | Local MCP client (Claude Desktop / Windsurf / Cursor) | ⚡⚡⚡ Fastest, zero network overhead |
| **`sse`** | Browser or old HTTP client | ⚡⚡ One-way stream push |
| **`streamable-http`** | Modern remote client (recommended) | ⚡⚡⚡ Bidirectional HTTP stream |
<br/>
<img src="https://user-images.githubusercontent.com/74038190/212284100-561aa473-3905-4a80-b561-0d28506553ee.gif" width="100%" height="3"/>
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
TOOL CATALOG
═══════════════════════════════════════════════════════════════════ -->
<h2>
<img src="https://user-images.githubusercontent.com/74038190/216122041-518ac897-8d92-4c6b-9b3f-ca01dcaf38ee.png" width="28" /> Tool Catalog
</h2>
<details>
<summary><b>📊 Click to expand the full toolset (24 categories · 90+ tools)</b></summary>
<br/>
| Domain | Count | Signature Tools |
|---|:-:|---|
| 🌐 **Generic Passthrough** | 1 | `panel_request` — call any 1Panel endpoint directly |
| 📊 **System & Dashboard** | 2 | `get_system_info` · `get_dashboard_info` |
| 🌍 **Websites** | 10 | `list_websites` · `create_website` · `update_website_https` |
| 🔐 **SSL Certificates** | 2 | `list_ssls` · `create_ssl` |
| 🛍️ **App Store** | 9 | `app_store_list` · `install_mysql` · `install_openresty` · `app_operate` |
| 💾 **Databases** | 7 | `list_databases` · `create_database` · `database_backup` · `redis_status` |
| 🐳 **Docker Containers** | 8 | `list_containers` · `container_create` · `container_exec` · `container_logs` |
| 🖼️ **Docker Images** | 5 | `list_images` · `image_pull` · `image_build` · `image_prune` |
| 🌐 **Networks & Volumes** | 7 | `list_networks` · `create_volume` · `delete_network` |
| 📜 **Docker Compose** | 6 | `list_compose` · `compose_up` · `compose_operate` |
| 📁 **Files** | 11 | `panel_file_list` · `panel_file_read` · `panel_file_compress` · `panel_file_wget` |
| 🛡️ **Firewall** | 8 | `firewall_status` · `list_firewall_rules` · `create_firewall_ip_rule` |
| ⏰ **Cron Jobs** | 5 | `list_crons` · `create_cron` · `handle_cron` |
| 🔧 **Processes** | 2 | `list_processes` · `stop_process` |
| 🔑 **SSH Service** | 5 | `ssh_info` · `ssh_operate` · `ssh_logs` · `ssh_generate_key` |
| ⚡ **Remote SSH Exec** ⭐ | 2 | `ssh_remote_exec` · `ssh_port_check` |
| 📝 **Logs** | 3 | `operation_logs` · `login_logs` · `system_logs` |
| 📈 **Monitoring** | 2 | `monitor_search` · `monitor_clean` |
| 💼 **Backups** | 4 | `list_backup_accounts` · `backup_operate` · `database_backup` |
| 📷 **Snapshots** | 4 | `list_snapshots` · `create_snapshot` · `recover_snapshot` |
| ⚙️ **System Settings** | 5 | `get_settings` · `update_password` · `update_panel_port` · `panel_upgrade` |
| 🧪 **Toolbox** | 10 | `toolbox_dns` · `toolbox_hosts` · `toolbox_swap` · `toolbox_fail2ban_status` |
| 🌱 **Runtimes** | 3 | `list_runtimes` · `create_runtime` · `runtime_operate` |
| 💻 **Local Shell** | 1 | `shell_exec` — local cmd / bash / pwsh |
| 📂 **Local Filesystem** | 6 | `local_file_read` · `local_file_write` · `local_file_search` |
> Full registration code: [`main.go::addTools()`](main.go).
</details>
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
QUICK START
═══════════════════════════════════════════════════════════════════ -->
<h2>
⚡ Quick Start
</h2>
<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=14&pause=1000&color=00C896¢er=true&vCenter=true&width=900&lines=%24+go+build+-o+mcp-1panel-full+.;%24+.%2Fmcp-1panel-full+--token+YOUR_KEY+--host+http%3A%2F%2F127.0.0.1%3A9999;%E2%9C%93+listening+on+stdio+%E2%80%A2+90%2B+tools+ready" />
### 1️⃣ Build from source
```bash
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
```bash
# 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
```bash
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
```
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
CLI FLAGS
═══════════════════════════════════════════════════════════════════ -->
<h2>🎛️ CLI Flags</h2>
<table>
<tr>
<th align="left">1Panel Connection</th>
<th align="left">Default</th>
<th align="left">Description</th>
</tr>
<tr><td><code>--token</code></td><td><i>required</i></td><td>1Panel API Key</td></tr>
<tr><td><code>--host</code></td><td><i>required</i></td><td>1Panel address, e.g. <code>http://127.0.0.1:9999</code></td></tr>
</table>
<table>
<tr>
<th align="left">Transport</th>
<th align="left">Default</th>
<th align="left">Description</th>
</tr>
<tr><td><code>--transport</code></td><td><code>stdio</code></td><td><code>stdio</code> · <code>sse</code> · <code>streamable-http</code></td></tr>
<tr><td><code>--addr</code></td><td><code>http://localhost:8000</code></td><td>HTTP listening address (HTTP transports only)</td></tr>
</table>
<table>
<tr>
<th align="left">SSH Defaults (optional)</th>
<th align="left">Default</th>
<th align="left">Description</th>
</tr>
<tr><td><code>--ssh-host</code></td><td><i>empty</i></td><td>Default SSH host (IP or domain)</td></tr>
<tr><td><code>--ssh-user</code></td><td><i>empty</i></td><td>Default SSH username</td></tr>
<tr><td><code>--ssh-key</code></td><td><i>empty</i></td><td>Default private key path</td></tr>
<tr><td><code>--ssh-password</code></td><td><i>empty</i></td><td>Default password (plaintext — discouraged)</td></tr>
<tr><td><code>--ssh-port</code></td><td><code>22</code></td><td>Default SSH port</td></tr>
</table>
<sub>💡 Pre-fill SSH defaults so AI calls only need <code>command</code>.</sub>
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
MCP CLIENT CONFIG
═══════════════════════════════════════════════════════════════════ -->
<h2>🔌 MCP Client Config</h2>
<details open>
<summary><b>Windsurf / Claude Desktop / Cursor</b> <sub>(click to toggle)</sub></summary>
```json
{
"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"
]
}
}
}
```
</details>
<details>
<summary><b>Linux / macOS</b> <sub>(click to toggle)</sub></summary>
```json
{
"mcpServers": {
"mcp-1panel-full": {
"command": "/usr/local/bin/mcp-1panel-full",
"args": [
"--token", "YOUR_API_KEY",
"--host", "http://127.0.0.1:9999"
]
}
}
}
```
</details>
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
SSH REMOTE EXECUTION
═══════════════════════════════════════════════════════════════════ -->
<h2>
<img src="https://user-images.githubusercontent.com/74038190/216122069-5b8169d7-1d8e-4a13-b245-a8e4176c99f8.png" width="28" /> SSH Remote Execution
</h2>
> The crown jewel of this server — a single tool that lets your AI run anything on remote hosts.
<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=14&pause=1500&color=FFD700&width=900&lines=ssh+ubuntu%4049.232.205.139+%22df+-h+%26%26+uptime%22;%E2%9C%93+exit%3D0+%E2%80%A2+stdout+captured+%E2%80%A2+structured+JSON+returned;%E2%9C%A6+password+%E2%80%A2+key+%E2%80%A2+passphrase+%E2%80%A2+kbd-interactive" />
<table>
<tr>
<td valign="top" width="50%">
#### 📞 Two ways to call
**Option A — Pass everything per call:**
```json
{
"host": "1.2.3.4",
"user": "ubuntu",
"keyPath": "/path/to/id_rsa",
"command": "df -h"
}
```
**Option B — Use CLI defaults:**
```json
{ "command": "df -h" }
```
</td>
<td valign="top" width="50%">
#### 🔐 Auth methods supported
| Field | Purpose |
|---|---|
| `password` | Plain password |
| `keyPath` | Path to private key file |
| `keyContent` | PEM key content directly |
| `keyPassphrase` | Decrypt encrypted private key |
Auto-fallback to **`keyboard-interactive`** for servers with `PasswordAuthentication no`.
</td>
</tr>
</table>
#### 📤 Output format
```text
exit=0
--- stdout ---
ubuntu
VM-0-5-ubuntu
--- stderr ---
```
Plus structured JSON: `{ host, user, port, command, stdout, stderr, exitCode }`.
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
EXAMPLES
═══════════════════════════════════════════════════════════════════ -->
<h2>
💬 Real-World Conversations
</h2>
> *Watch how natural language unfolds into precise tool calls.*
<div align="center">
<img src="https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=500&size=15&pause=1500&color=58A6FF¢er=true&vCenter=true&width=720&lines=You+talk.+The+AI+listens.+Tools+do+the+work.;Six+stories.+Six+commands.+Zero+terminals." />
</div>
<table>
<tr>
<td valign="top" width="50%">
#### 🩺 *"How is my server doing?"*
```
AI ➜ get_dashboard_info()
↳ CPU 5%, Mem 6%, Disk 12%, Uptime 2:03
```
#### 📦 *"Install Redis on port 6380."*
```
AI ➜ app_store_list("redis")
AI ➜ panel_request POST /apps/install
{ name: "redis", port: 6380, ... }
```
#### 🗄️ *"Backup all my MySQL databases."*
```
AI ➜ list_databases() → 5 dbs
AI ➜ database_backup × 5 in parallel
```
</td>
<td valign="top" width="50%">
#### 🔥 *"Block IP 1.2.3.4 in firewall."*
```
AI ➜ create_firewall_ip_rule(
address: "1.2.3.4",
strategy: "drop"
)
```
#### 🐛 *"Why is nginx failing?"*
```
AI ➜ list_installed_apps() → openresty
AI ➜ app_installed_detail(id)
AI ➜ container_logs(id, tail=100)
```
#### ⚡ *"Free up /tmp on remote server."*
```
AI ➜ ssh_remote_exec(
command: "find /tmp -size +100M -delete"
)
```
</td>
</tr>
</table>
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
PROJECT LAYOUT
═══════════════════════════════════════════════════════════════════ -->
<h2>🗂️ Project Layout</h2>
```
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
```
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
TROUBLESHOOTING
═══════════════════════════════════════════════════════════════════ -->
<h2>🩺 Troubleshooting</h2>
<details>
<summary><b><code>dial tcp :22:</code> SSH error</b></summary>
<br/>
CLI default `--ssh-host` is not active. Check:
1. `mcp_config.json` includes `--ssh-host`
2. **Restart the MCP client itself** (not just refresh tools)
3. Inspect `logs/mcp-1panel-full.log` for `[ssh] defaults set: ...`
</details>
<details>
<summary><b><code>Request parameter error</code> / 1Panel API 400 errors</b></summary>
<br/>
Some 1Panel endpoints validate required fields strictly. This project pre-fills sensible defaults for hot endpoints (`list_databases`, `list_backup_records`, `firewall_status`, `monitor_search`).
If something still fails, fall back to **`panel_request`** with an explicit payload.
</details>
<details>
<summary><b><code>Not Found (code: 404)</code> from 1Panel API</b></summary>
<br/>
API paths differ between 1Panel versions. This project targets **v2.0.15**.
For newer or custom routes, use the universal `panel_request` tool.
</details>
<details>
<summary><b>Token authentication failed</b></summary>
<br/>
1. Confirm 1Panel API interface is **enabled**
2. Confirm the client IP is in the **whitelist**
3. Tokens are case-sensitive — copy the entire string
</details>
<details>
<summary><b><code>transport error: transport closed</code></b></summary>
<br/>
The MCP client lost the stdio process. Force a restart:
| Client | Action |
|---|---|
| **Windsurf** | `Ctrl+Shift+P` → `Reload Window` |
| **Claude Desktop** | Quit completely, then relaunch |
| **Cursor** | Restart Cursor |
</details>
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
SECURITY
═══════════════════════════════════════════════════════════════════ -->
<h2>🛡️ Security</h2>
> ⚠️ **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
#### Best Practices
- 🔐 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
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
CHANGELOG
═══════════════════════════════════════════════════════════════════ -->
<h2>📜 Changelog</h2>
<details open>
<summary><b>v1.0.0</b> <sub>2026-04</sub> <sub>(click to toggle)</sub></summary>
<br/>
✨ **New**
- `ssh_remote_exec` & `ssh_port_check` — password / key / encrypted-key auth
- CLI flags `--ssh-host` `--ssh-user` `--ssh-key` `--ssh-password` `--ssh-port` for sticky defaults
- 90+ tool registry · structured output everywhere
🩹 **Fixes (1Panel v2.0.15)**
- `firewall_status` — adds required `name` field
- `monitor_search` — auto-fills time window
- `list_databases` — corrects `orderBy` validation
- `list_backup_records` — defaults `type`
- `list_processes` — switches to `/process/:pid` (`/process/listening` removed upstream)
🛠️ **Internal**
- Logs path now resolves next to executable — survives any working directory
- Removed duplicate tool registrations (`tools/localssh`)
</details>
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
ACKNOWLEDGEMENTS
═══════════════════════════════════════════════════════════════════ -->
<h2>💎 Acknowledgements</h2>
<table>
<tr>
<td align="center" width="25%">
<a href="https://github.com/1Panel-dev/1Panel">
<img src="https://avatars.githubusercontent.com/u/119326914?s=200&v=4" width="60" height="60"/><br/>
<b>1Panel</b>
</a>
<br/><sub>Modern Linux panel</sub>
</td>
<td align="center" width="25%">
<a href="https://github.com/1Panel-dev/mcp-1panel">
<img src="https://avatars.githubusercontent.com/u/119326914?s=200&v=4" width="60" height="60"/><br/>
<b>mcp-1panel</b>
</a>
<br/><sub>Original MCP server</sub>
</td>
<td align="center" width="25%">
<a href="https://modelcontextprotocol.io/">
<img src="https://avatars.githubusercontent.com/u/182288589?s=200&v=4" width="60" height="60"/><br/>
<b>MCP</b>
</a>
<br/><sub>The protocol</sub>
</td>
<td align="center" width="25%">
<a href="https://pkg.go.dev/golang.org/x/crypto/ssh">
<img src="https://go.dev/images/go-logo-blue.svg" width="60" height="60"/><br/>
<b>x/crypto/ssh</b>
</a>
<br/><sub>SSH client for Go</sub>
</td>
</tr>
</table>
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
LICENSE
═══════════════════════════════════════════════════════════════════ -->
<h2>📄 License</h2>
Released under **GNU General Public License v3.0** — see [LICENSE](LICENSE).
> Any modification, redistribution or derivative work must remain open under the same license and preserve copyright.
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
STAR HISTORY
═══════════════════════════════════════════════════════════════════ -->
<img src="https://user-images.githubusercontent.com/74038190/212284100-561aa473-3905-4a80-b561-0d28506553ee.gif" width="100%" height="3"/>
<br/>
<div align="center">
<h2>
⭐ Star History
</h2>
<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=500&size=14&pause=1000&color=FFD700¢er=true&vCenter=true&width=520&lines=%E2%98%85+Every+star+is+a+vote+of+confidence+%E2%98%85;%E2%98%85+Help+more+folks+discover+this+project+%E2%98%85" />
<br/><br/>
<a href="https://www.star-history.com/#Aurora100729/mcp-1panel-full&Date">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Aurora100729/mcp-1panel-full&type=Date&theme=dark" />
<img src="https://api.star-history.com/svg?repos=Aurora100729/mcp-1panel-full&type=Date" />
</picture>
</a>
<br/><br/>
<sub><i>If this project saved you a click — give it a ⭐</i></sub>
</div>
<br/>
<!-- ═══════════════════════════════════════════════════════════════════
FOOTER WAVE
═══════════════════════════════════════════════════════════════════ -->
<div align="center">
<img src="https://user-images.githubusercontent.com/74038190/212284100-561aa473-3905-4a80-b561-0d28506553ee.gif" width="100%" height="3"/>
<br/>
```diff
@@ Conversations > Commands. Intent > Syntax. AI > Toil. @@
+ Built with care · Open to all · Made for the curious
```
<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=400&size=13&pause=2000&color=8B949E¢er=true&vCenter=true&width=640&lines=%E2%9C%A6+Crafted+with+%E2%99%A5+by+Aurora+%E2%9C%A6;%E2%9C%A6+Built+for+humans+who+talk+to+machines+%E2%9C%A6" />
<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=0:1a1a2e,50:16213e,100:0f3460&height=140§ion=footer" />
</div>
