SSH MCP Server — VS Code Extension
Exposes a full-featured SSH Model Context Protocol (MCP) server to GitHub Copilot and any other MCP-aware AI agent running inside VS Code.
VS Code 1.99 + GitHub Copilot required.
Installation
Install the extension from the VS Code Marketplace (or from a .vsix file).
That is all. No mcp.json configuration is required.
The extension implements VS Code's McpServerDefinitionProvider API, which causes the SSH MCP server to appear automatically in Copilot's tool list the moment the extension activates — the same mechanism used by the Chrome DevTools MCP extension. VS Code manages the server process lifecycle; you never edit a JSON file.
Verifying it works
- Open Copilot Chat (
Ctrl+Alt+I)
- Click the tools icon (wrench) at the bottom of the chat input
- You should see "SSH MCP Server" listed with all 20 tools expandable
If the server does not appear, run SSH MCP: Restart MCP Server from the Command Palette (Ctrl+Shift+P).
Session Management
| Tool |
Description |
ssh_connect |
Open an SSH session (key or password auth) |
ssh_disconnect |
Close a session |
ssh_list_sessions |
List active sessions and remaining connection slots |
ssh_session_ping |
Health-check a session before write-critical operations |
Command Execution
| Tool |
Description |
ssh_exec |
Run a command and capture stdout/stderr/exit code (blocking) |
ssh_sudo_exec |
Run a command with sudo, password injected via stdin |
ssh_exec_background |
Start a long-running command; returns immediately with a jobId |
ssh_exec_poll |
Read accumulated output and status of a background job |
ssh_exec_poll_list |
List all background jobs (running + completed) |
ssh_exec_cancel |
Cancel a running background job |
Interactive Shell (PTY)
| Tool |
Description |
ssh_shell_open |
Open a PTY shell channel |
ssh_shell_write |
Write data / commands to shell stdin |
ssh_shell_read |
Read and drain buffered shell output |
ssh_shell_resize |
Resize the PTY window |
ssh_shell_close |
Close a shell channel |
ssh_shell_list |
List all open shell channels |
SFTP
| Tool |
Description |
ssh_sftp_list |
List a remote directory |
ssh_sftp_upload_local |
Upload a file from the local machine to the remote host (streaming, any size/type) |
ssh_sftp_download_local |
Download a file from the remote host to the local machine (streaming, any size/type) |
ssh_sftp_delete |
Delete a remote file |
Logging
| Tool |
Description |
ssh_get_logs |
Query the structured event log (filter by kind, host, session, time) |
Configuration (optional)
Change settings in VS Code Settings (sshMcp.*). The extension reads them at activation and passes them as environment variables to the server process — no manual JSON editing needed.
| VS Code Setting |
Environment Variable |
Default |
Description |
sshMcp.maxConnections |
SSH_MCP_MAX_CONNECTIONS |
10 |
Max simultaneous SSH sessions |
sshMcp.logDir |
SSH_MCP_LOG_DIR |
~/.ssh-mcp/logs |
NDJSON log file directory |
sshMcp.sqlitePath |
SSH_MCP_SQLITE_PATH |
~/.ssh-mcp/logs/events.db |
SQLite audit database path |
sshMcp.defaultTerm |
SSH_MCP_DEFAULT_TERM |
xterm-256color |
PTY TERM variable |
sshMcp.defaultCols |
SSH_MCP_DEFAULT_COLS |
220 |
PTY default width in columns |
sshMcp.defaultRows |
SSH_MCP_DEFAULT_ROWS |
50 |
PTY default height in rows |
sshMcp.shellReadTimeoutMs |
SSH_MCP_SHELL_READ_TIMEOUT_MS |
5000 |
ssh_shell_read timeout (ms) |
Commands
| Command |
Description |
| SSH MCP: Restart MCP Server |
Force VS Code to restart the server process |
| SSH MCP: Open Log Directory |
Reveal the log folder in the OS file manager |
How it works
The extension registers an McpServerDefinitionProvider. When VS Code needs the server it calls provideMcpServerDefinitions(), which returns a McpStdioServerDefinition that launches the bundled Node.js server as a child process on stdio. VS Code owns the process; Copilot communicates with it via JSON-RPC / MCP protocol.
GitHub Copilot
|
| JSON-RPC / stdio (managed by VS Code)
v
SSH MCP Server (Node.js, bundled inside .vsix at server/dist/index.js)
|
| ssh2 library
v
Remote SSH hosts
Key properties:
- Zero path configuration — the server path is resolved at runtime from the extension's own install directory. VS Code knows where that is; the user does not need to.
- No separate Node.js install —
process.execPath (the Node binary already running VS Code) is used to spawn the server.
- Settings-driven —
sshMcp.* VS Code settings are translated to SSH_MCP_* env vars automatically.
- SSH keepalive — every connection sends a keepalive probe every 15 s (3-retry limit) so sessions survive long agent operations without silent expiry.
Is this useful for AI agents?
An AI agent with these tools can:
- Inspect production systems — run
df -h, free -m, systemctl status without copy-paste.
- Iterate on live code — write a patch via SFTP, restart a service, read the new logs, all in one loop.
- Debug incidents — grep syslog, tail application logs, query databases, analyse core dumps.
- Provision infrastructure — install packages, edit config files, run Ansible or Terraform plans.
- Run long builds —
ssh_exec_background + ssh_exec_poll for multi-minute operations without blocking.
Every action is structured, logged, and auditable. Full command history is available through ssh_get_logs.
Building from source (contributors only)
End users should install the .vsix. This section is for contributors.
# 1. Build the MCP server
cd <repo-root>
npm install && npm run build
# 2. Compile the extension and sync the server bundle into place
cd vscode-extension
npm install && npm run compile
# Windows
xcopy /S /Y ..\dist\* server\dist\
# macOS / Linux
cp -r ../dist/* server/dist/
# 3. Package
npx vsce package --no-dependencies
# => ssh-mcp-1.1.0.vsix
# 4. Install
code --install-extension ssh-mcp-1.1.0.vsix
Requirements
- VS Code 1.99+
- GitHub Copilot extension
License
MIT
