Provides MCP HTTP endpoints and tools to manage SSH targets and one-time WebShell sessions via an embedded WebShell gateway.
Configuration
View docs{
"mcpServers": {
"have-myn-ssh-mcp": {
"url": "http://localhost:3001/mcp",
"headers": {
"PORT": "3001",
"WEBSHELL_DB_HOST": "mysql",
"WEBSHELL_DB_PORT": "3306",
"WEBSHELL_DB_USER": "webshell",
"MOCK_WEBSHELL_PORT": "9100",
"SSH_WEBSHELL_API_URL": "http://localhost:9100",
"WEBSHELL_DB_DATABASE": "webshell",
"WEBSHELL_DB_PASSWORD": "webshell_pass",
"SSH_WEBSHELL_API_TOKEN": "YOUR_API_TOKEN",
"WEBSHELL_PUBLIC_BASE_URL": "http://localhost:9100",
"SSH_WEBSHELL_HTTP_TIMEOUT_MS": "15000"
}
}
}
}SSH MCP provides an MCP Server that exposes WebShell gateway capabilities as MCP tools over HTTP. You can use it to discover SSH targets, create one-time WebShell sessions, and open interactive terminals through a centralized MCP interface.
You interact with SSH MCP through an MCP client to manage SSH targets and start WebShell sessions. Use the available tools to list targets, create a one-time WebShell link, or open a terminal for a specific target. The MCP HTTP endpoints are exposed for control and streaming, while the inline WebShell gateway handles the actual terminal sessions.
Prerequisites you need before installation:
Concrete installation steps you can follow to get SSH MCP up and running:
# Option A: Docker Compose (recommended for production and testing)
docker compose up -d --build
# Option B: Docker build and run (single container, external MySQL)
docker build -t ssh-mcp:latest .
docker run -d \
-p 3001:3001 \
-e PORT=3001 \
-e SSH_WEBSHELL_API_URL=http://localhost:9100 \
-e MOCK_WEBSHELL_PORT=9100 \
-e WEBSHELL_DB_HOST=<YOUR_MYSQL_HOST> \
-e WEBSHELL_DB_PORT=3306 \
-e WEBSHELL_DB_USER=webshell \
-e WEBSHELL_DB_PASSWORD=webshell_pass \
-e WEBSHELL_DB_DATABASE=webshell \
--name ssh-mcp \
ssh-mcp:latest
# Option C: Local development
npm install
npm run build
npm startConfigure the server using the following environment variables. These values control how the MCP server talks to the inline WebShell gateway and the MySQL database.
PORT=3001
# WebShell gateway connection
SSH_WEBSHELL_API_URL=http://localhost:9100
SSH_WEBSHELL_HTTP_TIMEOUT_MS=15000
SSH_WEBSHELL_API_TOKEN=YOUR_API_TOKEN
# Inline WebShell Gateway (embedded in SSH MCP)
MOCK_WEBSHELL_PORT=9100
WEBSHELL_PUBLIC_BASE_URL=http://localhost:9100
# MySQL connection
WEBSHELL_DB_HOST=127.0.0.1
WEBSHELL_DB_PORT=3306
WEBSHELL_DB_USER=webshell
WEBSHELL_DB_PASSWORD=webshell_pass
WEBSHELL_DB_DATABASE=webshellSSH MCP stores SSH targets and session history in MySQL. You will interact with two main tables: targets and sessions. The targets table holds host, port, credentials, and an optional private key. The sessions table keeps start and end times, status, and a reference to the target for auditing and analytics.
When you create a session, a one-time WebShell link is generated. Opening the link renders a WebShell terminal page and establishes a WebSocket connection for the live session.
In production, set up a dedicated database user with the minimum permissions needed. Consider exposing the WebShell gateway behind a reverse proxy with TLS and WAF rules. If you require additional auth for the MCP side, implement RBAC or token validation on API calls. Treat session links as short-lived credentials and avoid distributing them to untrusted environments.
For long-term operation, monitor resource usage and tune timeouts according to your workload. Plan for periodic maintenance windows and automated backups of the MySQL data.
If you encounter port conflicts, adjust the PORT value or stop the process using the port. In Docker setups, modify the host port mappings in docker-compose.yml if 3001 or 9100 is occupied.
If the WebShell gateway is unreachable, verify the SSH_WEBSHELL_API_URL value and ensure the gateway port is accessible from the container network. Confirm WEBSHELL_PUBLIC_BASE_URL matches the external access address.
If list_ssh_targets returns no data, double-check the WEBSHELL_DB_* variables and ensure the database is reachable. Check MySQL status and the targets table contents.
Sessions are tracked in a memory map for quick access while the gateway is running. Start times, end times, status, and a reason are stored in the sessions table for auditing. Sessions in memory are not restored after a restart; existing links become unavailable.
The sessions table can be used to generate reports or feed into an external audit system. A separate auth_sessions table exists for potential future authentication features.
SSH MCP exposes the following MCP tools to manage SSH targets and sessions:
- create_ssh_web_terminal: Create a one-time session record in the database and return a one-time WebShell session link.
- open_ssh_terminal: Match user input to a target and reuse the create_ssh_web_terminal logic to return a session link.
In Docker Compose deployments, MySQL runs on port 3306 and the SSH MCP container exposes 3001 for MCP control and 9100 for the WebShell session page. The MCP container uses http://localhost:9100 to call the embedded gateway internally.
Reads SSH targets from the MySQL targets table and returns a JSON structure that lists available SSH targets.
Creates a one-time session record in the database and returns a one-time WebShell session link that can be opened by a client.
Matches the user's input to an SSH target and reuses the create_ssh_web_terminal logic to provide a session link.