# heyjishh/cloudpanel-mcp architecture

> Architecture diagram of the GitHub repository heyjishh/cloudpanel-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/heyjishh/cloudpanel-mcp
- Repository: https://github.com/heyjishh/cloudpanel-mcp

## Overview

CloudPanel MCP Server exposes server-management tools to AI clients, then executes remote commands over a persistent SSH connection. Its principal workflow is an MCP request, tool dispatch, SSH command execution on a managed VPS, and a result returned to the client. The README documents broad tool categories, including deployment and server installation; the excerpts show representative command execution, but not every handler. The CLI also configures client integrations, and the Python package forwards invocations to the npm CLI.

Main entry points: [`src/index.ts`](https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/index.ts) (MCP Server), [`src/ssh.ts`](https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/ssh.ts) (Persistent SSH), [`src/cli.ts`](https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/cli.ts) (Node CLI), [`python/src/cloudpanel_mcp/cli.py`](https://github.com/heyjishh/cloudpanel-mcp/blob/master/python/src/cloudpanel_mcp/cli.py) (Python Wrapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP Runtime"]
  node_mcp_server["MCP Server<br/>[index.ts]"]
  node_ssh_client["Persistent SSH<br/>[ssh.ts]"]
end

subgraph group_management["VPS Management"]
  node_cloudpanel_ops["CloudPanel Tools<br/>[index.ts]"]
  node_docker_ops["Docker Tools<br/>[index.ts]"]
  node_server_install["Software Install<br/>[index.ts]"]
  node_firewall_dns["Firewall &amp; DNS<br/>[index.ts]"]
end

subgraph group_deployment["Deployment &amp; Operations"]
  node_deployment_tools["Project Deploy<br/>[index.ts]"]
  node_raw_command["Raw Command<br/>[index.ts]"]
end

subgraph group_setup["Client Setup"]
  node_cli["Node CLI<br/>[cli.ts]"]
  node_python_wrapper["Python Wrapper<br/>[cli.py]"]
end

node_ai_client(("AI Client"))
node_vps["Managed VPS"]

node_ai_client -->|"sends MCP requests"| node_mcp_server
node_mcp_server -->|"returns tool results"| node_ai_client
node_mcp_server -->|"dispatches tools"| node_cloudpanel_ops
node_mcp_server -->|"dispatches tools"| node_docker_ops
node_mcp_server -->|"dispatches tools"| node_server_install
node_mcp_server -->|"dispatches tools"| node_firewall_dns
node_mcp_server -->|"dispatches tool"| node_deployment_tools
node_mcp_server -->|"dispatches tool"| node_raw_command
node_cloudpanel_ops -->|"runs remote commands"| node_ssh_client
node_docker_ops -->|"runs remote commands"| node_ssh_client
node_server_install -->|"runs remote commands"| node_ssh_client
node_deployment_tools -->|"runs remote commands"| node_ssh_client
node_firewall_dns -.->|"runs remote commands"| node_ssh_client
node_raw_command -.->|"runs remote commands"| node_ssh_client
node_ssh_client -->|"executes SSH commands"| node_vps
node_cli -->|"starts server"| node_mcp_server
node_python_wrapper -->|"forwards invocation"| node_cli

click node_mcp_server "https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/index.ts"
click node_ssh_client "https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/ssh.ts"
click node_cloudpanel_ops "https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/index.ts"
click node_docker_ops "https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/index.ts"
click node_server_install "https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/index.ts"
click node_firewall_dns "https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/index.ts"
click node_deployment_tools "https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/index.ts"
click node_raw_command "https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/index.ts"
click node_cli "https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/cli.ts"
click node_python_wrapper "https://github.com/heyjishh/cloudpanel-mcp/blob/master/python/src/cloudpanel_mcp/cli.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp_server,node_ssh_client,node_ai_client toneBlue
class node_cloudpanel_ops,node_docker_ops,node_server_install,node_firewall_dns toneAmber
class node_deployment_tools,node_raw_command toneMint
class node_cli,node_python_wrapper toneRose
class node_vps toneIndigo
```

## Components

### MCP Runtime

- [MCP Server](https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/index.ts): `src/index.ts`
- [Persistent SSH](https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/ssh.ts): `src/ssh.ts`

### VPS Management

- [CloudPanel Tools](https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/index.ts): `src/index.ts`
- [Docker Tools](https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/index.ts): `src/index.ts`
- [Software Install](https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/index.ts): `src/index.ts`
- [Firewall & DNS](https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/index.ts): `src/index.ts`

### Deployment & Operations

- [Project Deploy](https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/index.ts): `src/index.ts`
- [Raw Command](https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/index.ts): `src/index.ts`

### Client Setup

- [Node CLI](https://github.com/heyjishh/cloudpanel-mcp/blob/master/src/cli.ts): `src/cli.ts`
- [Python Wrapper](https://github.com/heyjishh/cloudpanel-mcp/blob/master/python/src/cloudpanel_mcp/cli.py): `python/src/cloudpanel_mcp/cli.py`

### Other components

- **AI Client**
- **Managed VPS**

## Connections

- AI Client → MCP Server: sends MCP requests (evidence: `README.md`)
- MCP Server → AI Client: returns tool results (evidence: `README.md`)
- MCP Server → CloudPanel Tools: dispatches tools (evidence: `README.md`)
- MCP Server → Docker Tools: dispatches tools (evidence: `README.md`)
- MCP Server → Software Install: dispatches tools (evidence: `README.md`)
- MCP Server → Firewall & DNS: dispatches tools (evidence: `README.md`)
- MCP Server → Project Deploy: dispatches tool (evidence: `README.md`)
- MCP Server → Raw Command: dispatches tool (evidence: `README.md`)
- CloudPanel Tools → Persistent SSH: runs remote commands (evidence: `src/index.ts`)
- Docker Tools → Persistent SSH: runs remote commands (evidence: `src/index.ts`)
- Software Install → Persistent SSH: runs remote commands (evidence: `src/index.ts`)
- Project Deploy → Persistent SSH: runs remote commands (evidence: `src/index.ts`)
- Firewall & DNS → Persistent SSH: runs remote commands (evidence: `src/index.ts`)
- Raw Command → Persistent SSH: runs remote commands (evidence: `src/index.ts`)
- Persistent SSH → Managed VPS: executes SSH commands (evidence: `README.md`)
- Node CLI → MCP Server: starts server (evidence: `src/cli.ts`)
- Python Wrapper → Node CLI: forwards invocation (evidence: `python/src/cloudpanel_mcp/cli.py`)
