SSH MCP Server
Enables VS Code Copilot Chat to perform hardened SSH operations and manage remote Linux systems through a natural language interface using the Model Context Protocol.
Allows secure management of remote Linux servers via SSH, providing tools for host discovery, templated command execution, SFTP file transfers, and SSH certificate lifecycle management.
What Is This?
SSH MCP Server lets you manage remote Linux servers through natural language in VS Code Copilot Chat. Instead of switching to a terminal and remembering SSH commands, you just ask:
"Check disk usage on production-web"
"Show me the last 200 lines of /var/log/nginx/error.log on staging"
"Download /var/log/syslog from web-server-01 for incident INC-2026-0309"
The server enforces strict security policies — no raw shell access, all commands go through pre-approved templates, parameters are regex-validated, secrets in output are auto-redacted, and privileged operations require an approval workflow.
Related MCP server: mcp-ssh
Features
23 MCP tools — host discovery, session management, command execution (sync + background), file transfer, SFTP operations, SSH key management, certificate lifecycle, approval workflows
Template-only execution — no raw shell; every command matches a registered template with regex-validated parameters
3-tier security model — read-only (Tier 0), controlled mutation with confirmation (Tier 1), privileged with approval workflow (Tier 2)
Automatic secret redaction — AWS keys, bearer tokens, passwords, private keys are scrubbed from output
Tamper-evident audit log — every operation is logged with hash-chain integrity verification
Short-lived SSH certificates — issue and revoke certificates with TTL enforcement via a local CA
Persistent SSH sessions — connection pooling with keepalive probes and configurable idle timeout
Background command execution — run long-running template commands asynchronously with output polling
Path traversal protection —
..sequences blocked in all path parameters and file transfersTransfer policy — allowed paths, blocked extensions, size limits, mandatory justification for downloads
Quick Start
Prerequisites
Python 3.11+
VS Code with GitHub Copilot extension
SSH access to at least one remote Linux host
Install
As vscode plugin
Follow instructions on link:
https://marketplace.visualstudio.com/items?itemName=bhayanak.ssh-mcp-server-secure
Python package: https://pypi.org/project/ssh-mcp-server-copilot/
Install from Source (for development / contributing)
git clone https://github.com/bhayanak/ssh-mcp-server.git
cd ssh-mcp-server
python -m venv .venv
source .venv/bin/activate # macOS/Linux
# .venv\Scripts\activate # Windows
pip install -e ".[dev]"For local development, create .vscode/mcp.json pointing to the local source:
{
"servers": {
"ssh-mcp": {
"type": "stdio",
"command": "${workspaceFolder}/.venv/bin/python",
"args": ["-m", "ssh_mcp.server"],
"env": {
"SSH_MCP_CONFIG_DIR": "${workspaceFolder}/config",
"SSH_MCP_HOSTS_FILE": "${workspaceFolder}/config/hosts.json",
"SSH_MCP_TEMPLATES_FILE": "${workspaceFolder}/config/templates.json",
"SSH_MCP_AUDIT_LOG_DIR": "${workspaceFolder}/audit_logs",
"SSH_MCP_CERT_DATA_DIR": "${workspaceFolder}/cert_data",
"SSH_MCP_APPROVAL_DATA_DIR": "${workspaceFolder}/approval_data",
"SSH_MCP_SSH_KNOWN_HOSTS_FILE": "~/.ssh/known_hosts"
}
}
}
}Configure Your Hosts
Edit the hosts file with your actual servers. If you used ssh-mcp-server-copilot init, edit ~/.ssh-mcp/hosts.json. If developing from source, edit config/hosts.json.
[
{
"host_id": "my-server",
"hostname": "192.168.1.10",
"port": 22,
"ssh_user": "deploy",
"labels": {"env": "production", "role": "web"},
"description": "Production web server",
"allowed_roles": ["operator", "admin"]
}
]Field | Required | Description |
| Yes | Unique identifier (alphanumeric, dots, dashes) |
| Yes | IP address or FQDN |
| No | SSH port (default: 22) |
| Yes* | Remote SSH username. If empty, uses your OS username |
| No | Key-value tags for organization |
| No | Human-readable description |
| No | Which roles can access this host (default: operator, admin) |
Set Up SSH Access
Your SSH key must be authorized on each host:
# Generate a key if you don't have one
ssh-keygen -t ed25519 -C "your-email@example.com"
# Copy to each host
ssh-copy-id -i ~/.ssh/id_ed25519.pub deploy@192.168.1.10
# Load into ssh-agent (required — the MCP server uses the agent)
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
# Verify access
ssh deploy@192.168.1.10 "echo OK"Add host keys to known_hosts:
ssh-keyscan -H 192.168.1.10 >> ~/.ssh/known_hostsStart Using
Open the workspace in VS Code
The MCP server auto-starts from
.vscode/mcp.jsonOpen Copilot Chat (Cmd+Shift+I / Ctrl+Shift+I)
Switch to "Agent" mode (critical — only Agent mode can invoke MCP tools)
Verify tools are loaded — click the tools icon in the chat input bar, you should see 23 tools from
ssh-mcp
Now just ask in natural language:
> List all my SSH hosts
> Check disk usage on my-server
> Show me the last 100 lines of /var/log/syslog on my-server
> What's the status of nginx on my-server?Tools (23)
Tier 0 — Read-Only (No Confirmation)
Tool | Description |
| List all configured SSH hosts with labels and metadata |
| Get OS, uptime, kernel info from a host |
| View the tamper-evident audit trail |
| List available command templates |
| View pending approval requests |
Session Management
Tool | Description |
| Open a persistent SSH session (returns session_id for reuse) |
| Close a persistent session |
| List active sessions and remaining connection slots |
| Health-check a session (liveness, idle time, uptime) |
Tier 1 — Controlled Mutation (Confirmation Required)
Tool | Description |
| Execute a template command on a host (supports |
| Download/upload files via SFTP with path and extension policies (supports |
Background Command Execution
Tool | Description |
| Start a template command in the background (returns job_id) |
| Read accumulated stdout/stderr of a background job (redacted) |
| List all background jobs (running + completed) |
| Cancel a running background job |
Enhanced SFTP
Tool | Description |
| List files in a remote directory (within allowed paths) |
| Delete a remote file (within allowed paths, requires justification) |
Tier 2 — Privileged (Approval Required)
Tool | Description |
| Register a public SSH key with TTL enforcement |
| Revoke a registered SSH key |
| Issue a short-lived SSH certificate via the local CA |
| Revoke a certificate and delete its PEM |
| Approval workflow for privileged ops |
Configuration
Command Templates
Templates define which commands can be executed. Edit config/templates.json:
[
{
"template_id": "disk_usage",
"description": "Show disk usage summary",
"command": "df -h",
"allowed_params": {},
"allowed_roles": ["developer", "operator", "admin"],
"timeout_seconds": 10,
"risk_level": "low"
},
{
"template_id": "tail_log",
"description": "Tail the last N lines of a log file",
"command": "tail -n {lines} {log_path}",
"allowed_params": {
"lines": "^[0-9]{1,5}$",
"log_path": "^/var/log/[a-zA-Z0-9_./-]+$"
},
"allowed_roles": ["operator", "admin"],
"timeout_seconds": 15,
"risk_level": "low"
}
]Each parameter is validated against a regex pattern before substitution. Path traversal (..) is blocked automatically.
Environment Variables
All configuration is via environment variables with the SSH_MCP_ prefix:
Variable | Default | Description |
|
| Base config directory (all other paths derive from this) |
|
| Path to hosts configuration |
|
| Path to command templates |
|
| Audit log directory |
|
| Certificate storage directory |
|
| Approval data directory |
|
| Max simultaneous SSH sessions |
|
| Idle session timeout (seconds) |
|
| SSH keepalive interval (seconds) |
|
| Max failed keepalive probes before disconnect |
|
| Max concurrent background jobs |
|
| Max output buffer per background job (1 MB) |
|
| Background job auto-expiry (1 hour) |
| (none) | Path to SSH known_hosts file |
|
| Require different user as approver |
| (none) | Bearer token (empty = dev mode) |
|
| SSH connection timeout |
Transfer Policy (Defaults)
Setting | Default |
Allowed paths |
|
Blocked extensions |
|
Max file size | 50 MB |
Require justification for downloads | Yes |
Roles
Role | Access |
| Read-only tools, low-risk commands |
| All Tier 0 + Tier 1 tools |
| All tools including Tier 2 (key/cert management) |
| Audit log access |
Security
Design Principles
No raw shell — all commands go through registered templates
Parameter validation — every parameter is regex-validated before substitution
Path traversal blocking —
..sequences rejected in all parameters and file pathsSecret redaction — AWS keys, bearer tokens, passwords, private keys automatically scrubbed from output
Approval workflow — privileged operations (key/cert management) require explicit approval with HMAC-verified tokens
Tamper-evident audit — hash-chained audit log for forensic analysis
Strict host validation — paramiko
RejectPolicyby default (no auto-accepting unknown hosts)TTL enforcement — SSH certificates and keys have configurable maximum lifetimes
Approval Workflow
Tier 2 operations follow a 3-step flow:
1. request_approval → returns request_id + one-time approval_token
2. approve_request → verifies HMAC token, marks approved
3. call the tool → pass approval_request_id, consumed after useWith REQUIRE_TWO_PARTY_APPROVAL=true (production), a different user must approve.
Audit Log Verification
python -c "
from ssh_mcp.audit import AuditLogger
from pathlib import Path
logger = AuditLogger(Path('audit_logs'))
ok, msg = logger.verify_chain()
print(f'Chain integrity: {ok} — {msg}')
"Testing
Unit Tests
# Run all tests
pytest tests/ -v
# With coverage
pytest tests/ -v --cov=ssh_mcpRuntime Directories (git-ignored, auto-created)
Directory | Purpose |
| Tamper-evident audit log ( |
| CA keys, issued certificates, revocation list |
| Pending and consumed approval requests |
CLI Reference
ssh-mcp-server-copilot --version # Print version
ssh-mcp-server-copilot init # Create ~/.ssh-mcp with default configs
ssh-mcp-server-copilot # Start MCP server (stdio transport)
ssh-mcp-server-copilot --config-dir PATH # Use custom config directory
ssh-mcp-server-copilot --config-dir PATH init # Init a custom config directoryContributing
Fork the repository
Create a feature branch:
git checkout -b feature/my-featureMake your changes
Run tests:
pytest tests/ -vLint:
ruff check src/ tests/Submit a pull request
License
Available Tools
23 toolsadd_ssh_keyA
Register a new SSH public key with policy checks.
Validates key format and strength. Enforces TTL limits from key policy. Requires ADMIN role and prior approval.
Risk level: high (requires approval).
Inputs: user_name (required), public_key (required), ttl_seconds, reason, +1 more. Returns: object
approve_requestA
Approve a pending approval request.
In two-party mode, the approver must be a different user from the requester.
Risk level: high (grants execution permission).
Inputs: request_id (required), approval_token (required). Returns: object
cancel_background_jobB
Cancel a running background job.
Risk level: medium (requires user confirmation).
Inputs: job_id (required). Returns: object
get_audit_logsB
Return the last N audit log entries. Read-only.
Risk level: low.
Inputs: last_n. Returns: object
get_host_factsA
Get safe host metadata (OS, uptime, kernel) — no secrets.
Risk level: low.
Inputs: host_id (required). Returns: object
issue_certA
Issue a short-lived SSH certificate for a user.
Certificates are signed by the local CA with a tight TTL. Requires ADMIN role and prior approval.
Risk level: high.
Inputs: user_id (required), principals, ttl_seconds, justification, +1 more. Returns: object
list_background_jobsA
List all background jobs (running + completed).
Risk level: low (read-only).
Inputs: no named parameters. Returns: object
list_hostsA
List all allowed SSH hosts with metadata (labels, roles, description).
No authentication required beyond basic identity. Risk level: low.
Inputs: no named parameters. Returns: object
list_pending_approvalsA
List all pending approval requests.
Risk level: low (read-only).
Inputs: no named parameters. Returns: object
list_templatesA
List all available command templates that can be used with run_ssh_command.
Each template defines a pre-approved command pattern with its allowed parameters, roles, and risk level. Use the template_id when calling run_ssh_command.
Risk level: low.
Inputs: no named parameters. Returns: object
poll_background_jobA
Read accumulated output and status of a background job (redacted).
Returns new stdout since last poll, plus current status and exit code. Risk level: low (read-only).
Inputs: job_id (required). Returns: object
remove_ssh_keyA
Revoke / remove an SSH key by its key_id.
Requires ADMIN role and prior approval. Risk level: high.
Inputs: key_id (required), reason, approval_request_id. Returns: object
request_approvalA
Request approval for a privileged (Tier 2) operation.
Returns a request_id and one-time approval_token. The token must be presented to the approver. The request_id is then passed to the privileged tool.
Risk level: low (creating a request is safe).
Inputs: action (required), justification (required), host_id, ticket_ref. Returns: object
revoke_certA
Revoke an issued SSH certificate.
Revoked certificates are added to the revocation list and their PEM files are deleted. Requires ADMIN role and prior approval.
Risk level: high.
Inputs: cert_id (required), reason, approval_request_id. Returns: object
run_ssh_commandA
Execute a pre-approved command template on a target host.
Use list_templates to discover available template_ids. Examples:
disk_usage: run df -h (no params needed)
service_status: check a systemd service (params: {"service": "docker"})
list_processes: show top processes by memory (no params needed)
tail_log: tail a log file (params: {"lines": "100", "log_path": "/var/log/syslog"})
Only commands from the template registry are allowed. Parameters are validated against per-template regex rules. Output is automatically redacted for secrets.
Pass session_id from ssh_connect to reuse a persistent connection.
Risk level: medium (requires user confirmation in VS Code).
Inputs: host_id (required), template_id (required), params, session_id. Returns: object
run_ssh_command_backgroundA
Start a template command in the background (non-blocking).
Returns a job_id immediately. Use poll_background_job to read output, list_background_jobs to see all jobs, or cancel_background_job to stop.
Same template-only security model as run_ssh_command. Risk level: medium (requires user confirmation).
Inputs: host_id (required), template_id (required), params. Returns: object
sftp_deleteA
Delete a remote file via SFTP.
Only files within allowed_paths can be deleted. Blocked extensions are enforced. Requires a justification. Risk level: medium (requires user confirmation).
Inputs: host_id (required), remote_path (required), justification, session_id. Returns: object
sftp_list_directoryA
List files and directories at a remote path.
Only paths within the configured allowed_paths are accessible. Risk level: low (read-only).
Inputs: host_id (required), remote_path (required), session_id. Returns: object
ssh_connectA
Open a persistent SSH session to a host.
Returns a session_id that can be passed to run_ssh_command and transfer_file to reuse the connection. Sessions have keepalive probes and auto-close after idle timeout.
Risk level: low.
Inputs: host_id (required). Returns: object
ssh_disconnectB
Close a persistent SSH session.
Risk level: low.
Inputs: session_id (required). Returns: object
ssh_list_sessionsA
List all active SSH sessions and remaining connection slots.
Risk level: low.
Inputs: no named parameters. Returns: object
ssh_session_pingA
Health-check a persistent SSH session.
Returns liveness, idle time, and uptime. Risk level: low.
Inputs: session_id (required). Returns: object
transfer_fileA
Upload or download a file to/from a remote host.
Enforces path policy, blocked extensions, and size limits. Downloads require a justification string. For uploads, provide local_path (the file to upload).
Pass session_id from ssh_connect to reuse a persistent connection.
Risk level: medium-high (requires user confirmation).
Inputs: host_id (required), direction (required), remote_path (required), local_path, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Tools are generally well-differentiated by resource and action (e.g., request_approval vs approve_request vs list_pending_approvals form a clear workflow). However, with 23 granular tools, some operational overlap exists between transfer_file and sftp_* operations, and the background job suite requires careful reading to distinguish from standard command execution.
While all tools use snake_case with clear verbs, the prefix conventions are inconsistent: SSH session tools use ssh_* (ssh_connect, ssh_list_sessions) but host operations use bare verbs (list_hosts, get_host_facts); SFTP operations use sftp_* while file transfer uses unprefixed transfer_file. This mixed convention forces agents to read carefully.
At 23 tools, this falls into the borderline-heavy range (16-25). While the server covers a complex domain (governed SSH access with approval workflows, background jobs, and certificate management), the surface feels granular—session management alone uses four distinct tools, suggesting potential for consolidation (e.g., combining list/poll/cancel into a job management tool).
Core workflows for approvals, background jobs, and sessions are complete, but notable gaps exist: there are tools to add/remove SSH keys and issue/revoke certificates, but no corresponding list_ssh_keys or list_certs to inspect current state. Similarly, SFTP supports delete and list but lacks explicit upload/download (relying on the separate transfer_file tool).
Maintenance
Related MCP Connectors
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Termalin's hosted MCP server. Claude, ChatGPT or any MCP client runs commands, moves files over SFTP, queries databases and reads server metrics and monitoring alerts on your servers, keylessly through Termalin Connectors: no SSH key is handed over and no inbound port is opened. Per-host command policy and an audit log. Needs a termal.in Pro or Team account (new accounts start with a 14-day Pro trial).
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
The OpenRouter MCP server plugs OpenRouter into the AI tools you already use. Once connected, your assistant can pull live OpenRouter data (models, prices, your credits, rankings, and docs) and send quick test messages, all without leaving your editor.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn SSH MCP server that enables users to connect to and manage remote servers directly from Claude Code. It provides tools to execute commands, monitor connection status, and dynamically manage server configurations through natural language.10244 npm6MIT
- AlicenseAqualityDmaintenanceMCP server for remote Linux/Unix server management via SSH, enabling command execution, system monitoring, file operations, and diagnostics through natural language.341MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol (MCP) SSH client server that provides autonomous SSH operations for GitHub Copilot and VS Code. Enable natural language SSH automation without manual prompts or GUI interactions.202MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for remote Linux server administration via SSH, integrating with Claude Code to manage Ubuntu/Debian servers.2-