mcp-ssh-tool
Allows natural language SSH automation via GitHub Copilot, enabling remote system management through commands such as connecting to servers, executing commands, file operations, package management, and service control.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-ssh-tool connect to 192.168.1.100 as admin"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-ssh-tool
A 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.
Quick Start
Install
Global install (recommended):
npm install -g mcp-ssh-toolOne-off run:
npx mcp-ssh-tool
MCP Client Configuration (VS Code / Claude Desktop / others)
Add to your MCP configuration (mcp.json, .vscode/mcp.json, or the Claude Desktop MCP config):
{
"servers": {
"ssh-mcp": {
"type": "stdio",
"command": "mcp-ssh-tool",
"args": []
}
}
}Usage Examples
Once configured, you can use natural language with your MCP client:
SSH Connection: "Connect to server 192.168.1.100 as admin using SSH key"
File Operations: "Read the content of /etc/nginx/nginx.conf on the server"
Command Execution: "Run 'systemctl status nginx' on the remote server"
Package Management: "Install htop package on Ubuntu server"
Service Control: "Restart the nginx service"
Available Tools
ssh_open_session- Establish SSH connection with various auth methodsssh_close_session- Close SSH sessionssh_list_sessions- List all active SSH sessionsssh_ping- Check if a session is alive and responsivessh_list_configured_hosts- List hosts from ~/.ssh/configssh_resolve_host- Resolve host alias from SSH configproc_exec- Execute commands remotely (with optional timeout)proc_sudo- Execute commands with sudo privilegesfs_read,fs_write,fs_list,fs_stat,fs_mkdir,fs_rm,fs_rename- File system operationsensure_package- Package managementensure_service- Service controlensure_line_in_file- File line managementpatch_apply- Apply patches to filesdetect_os- System information detection
Related MCP server: mcp-ssh-tool
Overview
The SSH MCP Server acts as a bridge between GitHub Copilot and remote systems via SSH. It supports:
Non-interactive SSH operations - No prompts or GUI interactions
Multiple authentication methods - Password, SSH keys, or SSH agent
Session management - Automatic connection pooling with TTL and LRU eviction
File system operations - Read, write, list, and manage remote files via SFTP
Process execution - Run commands and sudo operations remotely
High-level automation - Package management, service control, and configuration management
Security - Automatic redaction of sensitive data in logs
Architecture
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ GitHub Copilot │────│ SSH MCP Server │────│ Remote Systems │
│ / VS Code │ │ │ │ (via SSH) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
│ MCP stdio protocol │ Session management │ SSH + SFTP
│ │ LRU cache + TTL │
│ │ Auth strategies │Installation
Prerequisites
Node.js ≥ 18 (LTS)
SSH access to target systems
SSH keys or credentials for authentication
Install from npm
npm install -g mcp-ssh-toolBuild from source
git clone https://github.com/oaslananka/mcp-ssh-tool.git
cd mcp-ssh-tool
npm install
npm run build
npm linkCLI Flags
--help/-h: Show usage and examples.--version/-v: Print version.--stdio: Force stdio mode (default).
Note: This is an MCP stdio server. The terminal is not an interactive shell; use an MCP client (Claude Desktop, VS Code MCP, etc.) or send JSON-RPC over stdio.
Platform Notes
Linux / macOS: Uses POSIX shell wrappers with safe quoting. Default temp directory:
/tmp.Windows targets: Requires OpenSSH server/agent; key discovery checks
C:\\Users\\<you>\\.ssh\\. Commands are wrapped for PowerShell-safe execution. Package/service helpers are intentionally disabled on Windows targets.Host keys: Host key checking is relaxed by default. Set
STRICT_HOST_KEY_CHECKING=trueand optionallyKNOWN_HOSTS_PATHto enforce verification.
ChatGPT Desktop Integration
Quick Setup
npm run setup:chatgptThis command automatically configures ChatGPT Desktop to use mcp-ssh-tool.
Manual Setup
Add to your ChatGPT Desktop MCP config:
macOS:
~/Library/Application Support/ChatGPT/mcp.jsonWindows:
%APPDATA%\ChatGPT\mcp.jsonLinux:
~/.config/chatgpt/mcp.json
{
"mcpServers": {
"ssh-mcp-server": {
"name": "ssh-mcp-server",
"command": "npx",
"args": ["-y", "mcp-ssh-tool"]
}
}
}For detailed usage, see docs/chatgpt-usage.md.
VS Code Copilot Integration
User-level Configuration (Recommended)
Open VS Code and press Ctrl+Shift+P, then run "MCP: Open User Configuration".
Add to your mcp.json:
{
"servers": {
"ssh-mcp": {
"type": "stdio",
"command": "mcp-ssh-tool",
"args": []
}
}
}Workspace-level Configuration
Create .vscode/mcp.json in your workspace:
{
"servers": {
"ssh-mcp": {
"type": "stdio",
"command": "mcp-ssh-tool",
"args": []
}
}
}Verification
Restart VS Code
Open Copilot Chat
The SSH MCP tools should appear in the available tools list
Test with: "Connect to 192.168.1.100 as admin and run 'uname -a'"
Usage Examples
Basic Connection and Command Execution
"Connect to 10.11.12.13 as deployer with password 'mypass' and run 'df -h'"File Operations
"Connect to server.example.com as admin, read /etc/nginx/nginx.conf and show me the server blocks"System Administration
"Connect to 192.168.1.50 as root, install htop package, start nginx service, and list /var/www contents"Configuration Management
"Connect to web-server as admin, add these lines to /etc/hosts:
192.168.1.10 db-server
192.168.1.20 cache-server
Then restart networking service"API Reference
Session Management
ssh.openSession
Opens a new SSH session with authentication.
Input:
{
"host": "example.com",
"username": "admin",
"port": 22,
"auth": "auto",
"password": "optional",
"privateKey": "optional-inline-key",
"privateKeyPath": "optional-path",
"passphrase": "optional",
"useAgent": false,
"readyTimeoutMs": 20000,
"ttlMs": 900000
}Output:
{
"sessionId": "ssh-1645123456789-1",
"host": "example.com",
"username": "admin",
"expiresInMs": 900000
}ssh.closeSession
Closes an active SSH session.
Input:
{
"sessionId": "ssh-1645123456789-1"
}Output:
{
"ok": true
}Process Execution
proc.exec
Executes a command on the remote system.
Input:
{
"sessionId": "ssh-1645123456789-1",
"command": "ls -la /home",
"cwd": "/tmp",
"env": {"DEBUG": "1"}
}Output:
{
"code": 0,
"stdout": "total 12\ndrwxr-xr-x 3 root root 4096...",
"stderr": "",
"durationMs": 245
}proc.sudo
Executes a command with sudo privileges.
Input:
{
"sessionId": "ssh-1645123456789-1",
"command": "systemctl restart nginx",
"password": "sudo-password",
"cwd": "/etc"
}File System Operations
fs.read
Reads a file from the remote system.
Input:
{
"sessionId": "ssh-1645123456789-1",
"path": "/etc/hosts",
"encoding": "utf8"
}Output:
{
"data": "127.0.0.1 localhost\n::1 localhost\n..."
}fs.write
Writes data to a file (atomic operation using temp file + rename).
Input:
{
"sessionId": "ssh-1645123456789-1",
"path": "/tmp/config.txt",
"data": "server_name example.com;\nlisten 80;",
"mode": 644
}fs.stat
Gets file or directory statistics.
Output:
{
"size": 1024,
"mtime": "2024-01-15T10:30:00.000Z",
"mode": 33188,
"type": "file"
}fs.list
Lists directory contents with pagination.
Input:
{
"sessionId": "ssh-1645123456789-1",
"path": "/var/log",
"page": 0,
"limit": 50
}Output:
{
"entries": [
{
"name": "nginx",
"type": "directory",
"size": 4096,
"mtime": "2024-01-15T10:30:00.000Z",
"mode": 16877
}
],
"nextToken": "1"
}fs.mkdirp
Creates directories recursively (mkdir -p equivalent).
fs.rmrf
Removes files or directories recursively (rm -rf equivalent).
fs.rename
Renames or moves files and directories.
High-Level Operations
ensure.package
Ensures a package is installed using the system's package manager.
Input:
{
"sessionId": "ssh-1645123456789-1",
"name": "nginx",
"sudoPassword": "optional"
}Output:
{
"ok": true,
"pm": "apt",
"code": 0,
"stdout": "Package nginx is already installed",
"stderr": ""
}ensure.service
Manages system services (systemd or traditional service).
Input:
{
"sessionId": "ssh-1645123456789-1",
"name": "nginx",
"state": "started",
"sudoPassword": "optional"
}ensure.linesInFile
Ensures specific lines exist in a file (idempotent).
Input:
{
"sessionId": "ssh-1645123456789-1",
"path": "/etc/hosts",
"lines": ["192.168.1.10 db-server", "192.168.1.20 cache-server"],
"createIfMissing": true,
"sudoPassword": "optional"
}patch.apply
Applies a patch to a file using the patch command.
os.detect
Detects operating system information, package manager, and init system.
Output:
{
"platform": "linux",
"distro": "ubuntu",
"version": "22.04",
"arch": "x86_64",
"shell": "bash",
"packageManager": "apt",
"init": "systemd",
"defaultShell": "bash",
"tempDir": "/tmp"
}Authentication
The server supports multiple authentication methods with automatic fallback:
Authentication Strategy Priority
Password (if provided)
SSH Key (inline → path → auto-discovery)
SSH Agent (if available)
SSH Key Auto-Discovery
The server automatically searches for SSH keys in:
~/.ssh/id_ed25519~/.ssh/id_rsa~/.ssh/id_ecdsa
Note: DSA keys (
id_dsa) are no longer supported due to security concerns.
Custom key directory: Set SSH_DEFAULT_KEY_DIR environment variable.
Examples
Password Authentication:
{
"host": "server.com",
"username": "admin",
"auth": "password",
"password": "secret"
}SSH Key (inline):
{
"host": "server.com",
"username": "admin",
"auth": "key",
"privateKey": "-----BEGIN PRIVATE KEY-----\n...",
"passphrase": "optional"
}SSH Key (file path):
{
"host": "server.com",
"username": "admin",
"auth": "key",
"privateKeyPath": "/home/user/.ssh/id_rsa"
}SSH Agent:
{
"host": "server.com",
"username": "admin",
"auth": "agent"
}Configuration
Environment Variables
LOG_LEVEL- Logging level (error,warn,info,debug)SSH_DEFAULT_KEY_DIR- Custom SSH key directorySTRICT_HOST_KEY_CHECKING- Enable strict host key checkingKNOWN_HOSTS_PATH- Custom known_hosts file path
Default Settings
Connection timeout: 20 seconds
Session TTL: 15 minutes
Max concurrent sessions: 20
Host key checking: Relaxed (disabled by default)
Error Codes
The server returns structured error codes for machine-readable error handling:
EAUTH - Authentication failed
ECONN - Connection error
ETIMEOUT - Operation timeout
ENOSUDO - Sudo operation failed
EPMGR - Package manager not found
EFS - File system operation failed
EPATCH - Patch application failed
EBADREQ - Invalid request parameters
Each error includes:
name: Error class namecode: Machine-readable error codemessage: Human-readable error messagehint: Optional suggestion for resolution
Security Features
Data Redaction
Sensitive data is automatically redacted from logs:
Passwords
Private keys
Passphrases
Sudo passwords
SSH agent socket paths
Connection Security
Configurable host key verification
Support for known_hosts files
Connection timeout enforcement
Automatic session cleanup
Session Management
TTL-based session expiration
LRU cache eviction
Graceful connection cleanup
No persistent credential storage
Development
Setup
git clone https://github.com/oaslananka/mcp-ssh-tool.git
cd mcp-ssh-tool
npm installScripts
npm run build # Compile TypeScript
npm run dev # Watch mode compilation
npm run test # Run unit tests
npm run e2e # Run E2E tests (requires RUN_SSH_E2E=1)
npm run lint # Type-check (no emit)
npm run format # Run Prettier
npm run test:coverage
npm run docsTesting
Unit Tests:
npm testE2E Tests (optional):
RUN_SSH_E2E=1 npm run e2eLicense
MIT License
Copyright (c) 2025 Osman Aslan (oaslananka)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
E2E tests require a local Docker container or SSH server for testing.
Contributing
Follow TypeScript and ESLint rules
Add tests for new features
Update documentation
Ensure all tests pass
Use conventional commit messages
License
MIT License - see LICENSE file for details.
Related Links
Model Context Protocol - Official MCP documentation
VS Code MCP Guide - VS Code Copilot extensibility
GitHub Copilot - GitHub Copilot documentation
Available Tools
20 toolsensure_lines_in_fileB
Ensures specific lines are present or absent in a file
Inputs: sessionId (required), path (required), lines (required), state (required).
ensure_packageC
Ensures a package is installed or removed
Inputs: sessionId (required), name (required), state (required).
ensure_serviceC
Ensures a service is in the desired state
Inputs: sessionId (required), name (required), state (required).
fs_listB
Lists directory contents
Inputs: sessionId (required), path (required), page, limit.
fs_mkdirpA
Creates directories recursively
Inputs: sessionId (required), path (required), mode.
fs_readA
Reads a file from the remote system
Inputs: sessionId (required), path (required), encoding.
fs_renameC
Renames or moves a file/directory
Inputs: sessionId (required), from (required), to (required).
fs_rmrfB
Removes files or directories recursively
Inputs: sessionId (required), path (required).
fs_statC
Gets file or directory statistics
Inputs: sessionId (required), path (required).
fs_writeC
Writes data to a file on the remote system
Inputs: sessionId (required), path (required), data (required), mode.
os_detectC
Detects operating system and environment information
Inputs: sessionId (required).
patch_applyB
Applies a patch to a file
Inputs: sessionId (required), path (required), patch (required).
proc_execC
Executes a command on the remote system
Inputs: sessionId (required), command (required), cwd, env.
proc_sudoC
Executes a command with sudo privileges
Inputs: sessionId (required), command (required), password, cwd.
ssh_close_sessionC
Closes an SSH session
Inputs: sessionId (required).
ssh_list_configured_hostsA
Lists all hosts configured in ~/.ssh/config
Inputs: no named parameters.
ssh_list_sessionsB
Lists all active SSH sessions with their details
Inputs: no named parameters.
ssh_open_sessionC
Opens a new SSH session with authentication
Inputs: host (required), username (required), port, auth, +7 more.
ssh_pingB
Checks if an SSH session is still alive and responsive
Inputs: sessionId (required).
ssh_resolve_hostA
Resolves a host alias from ~/.ssh/config to connection parameters
Inputs: hostAlias (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool has a clear, distinct purpose. SSH session management, filesystem operations, system administration, and execution tools are all well-separated with no overlapping responsibilities.
Most tools follow a domain prefix pattern (ssh_, fs_, proc_, ensure_) with verb_noun structure. Minor inconsistency: patch_apply lacks a prefix, and os_detect is less descriptive, but overall pattern is clear.
20 tools is well-suited for the domain of SSH remote management, covering session lifecycle, file operations, package/service management, and execution without being overwhelming.
The tool set covers core SSH management tasks comprehensively. Minor gaps exist (e.g., file permissions, user management), but these are beyond the typical scope of an SSH toolkit.
Maintenance
Related MCP Connectors
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
SSH client, server management and one remote MCP URL for your machines, with human approvals.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- FlicenseAqualityDmaintenanceA local Model Context Protocol server that allows LLMs to securely execute shell commands on remote Linux and Windows systems via SSH connections.62-
- AlicenseAqualityAmaintenanceSSH automation MCP server that enables Claude and ChatGPT to execute commands, manage files, install packages, and control services on remote servers over SSH — supporting password, key, and agent authentication.331,267 npm4MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI assistants full SSH/SFTP remote operations — session management, command execution, interactive shells, file transfers, port forwarding, and system diagnostics.2MIT
- AlicenseAqualityCmaintenanceAn MCP server that gives AI agents SSH access to remote machines through your local OpenSSH client, enabling remote command execution, file transfer, persistent shell sessions, and port forwarding.1740MIT