Skip to content

README.md

Latest commit

 

History

History
242 lines (178 loc) · 8.18 KB

README.md

File metadata and controls

242 lines (178 loc) · 8.18 KB

SSH MCP Server

GitHub stars CI License: MIT TypeScript MCP SSH

English | 中文

Secure SSH access for MCP clients. ssh_mcp lets Claude Desktop, VS Code Copilot, Augment, and other MCP-compatible agents run remote commands through a safety-first SSH proxy with OpenSSH config compatibility, connection pooling, and output guardrails.

Project health

Why developers pick this project

  • Use the SSH config you already know: standard OpenSSH fields like Host, HostName, User, Port, IdentityFile, and ProxyJump
  • Safer than a raw shell bridge: built-in dangerous command blocking, per-host allowlists/denylists, output caps, and secret redaction
  • Fast for multi-step agent sessions: pooled SSH connections reduce reconnect overhead
  • Works with real MCP workflows: designed for Claude Desktop, VS Code Copilot, Augment, and any MCP-compatible client
  • Flexible for teams: merge project-level and user-level configs so shared hosts stay global while project overrides stay local

Great fit for

  • AI-assisted production troubleshooting
  • Safe observability and read-only operations on remote servers
  • DevOps and platform engineering copilots
  • Internal tooling that needs SSH access without handing an agent unlimited shell freedom

Quick start

1. Install and build

npm install
npm run build

2. Add the server to your MCP client

See the ready-to-copy examples in:

  • examples/mcp-config.claude.example.json
  • examples/mcp-config.vscode.example.json

Minimal Claude Desktop / Augment example:

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": [
        "/absolute/path/to/ssh-mcp-server/dist/index.js",
        "--project-root",
        "/path/to/your/project"
      ],
      "env": {}
    }
  }
}

Minimal VS Code MCP example:

{
  "servers": {
    "ssh": {
      "command": "node",
      "args": [
        "/absolute/path/to/ssh-mcp-server/dist/index.js",
        "--project-root",
        "${workspaceFolder}"
      ]
    }
  }
}

3. Configure SSH hosts

Copy examples/ssh.config.example to ssh.config in your project root, or initialize one through the MCP tool:

Use tool: ssh_init_config with scope="project"

Minimal example:

Host my-server
  HostName 192.168.1.100
  User ubuntu
  Port 22
  IdentityFile ~/.ssh/id_rsa
  # mcp-ssh:denylist = rm -rf,mkfs,dd,shutdown,reboot

4. Try a few prompts in your MCP client

  • "List all configured SSH hosts."
  • "Test the SSH connection to my-server."
  • "Run uptime && df -h on my-server."
  • "Show me the merged SSH config for my-server."

Core features

  • Dual-scope configuration: project-level (ssh.config) + user-level (~/.config/mcp-ssh/config) with automatic merging
  • Connection pooling: reuse SSH connections across commands with idle cleanup
  • Per-host security policy: allowlists, denylists, max timeout, and max output size
  • Output management: automatic truncation to protect LLM context windows
  • Sensitive data protection: private keys and sensitive environment values are sanitized in output
  • OpenSSH compatibility: keep using your normal host aliases and SSH habits

Configuration

Config file locations

Scope Path Purpose
Project <project-root>/ssh.config Hosts specific to the current project
User ~/.config/mcp-ssh/config Shared hosts across projects

Merge rule: project-level settings override user-level settings for hosts with the same name.

Security annotations

Add policies as comments inside a Host block:

# mcp-ssh:denylist = cmd1,cmd2      # Block these command patterns
# mcp-ssh:allowlist = cmd1,cmd2     # Only allow these command patterns
# mcp-ssh:maxTimeoutMs = 30000      # Max execution timeout for this host
# mcp-ssh:maxOutputChars = 5000     # Max output characters for this host

Authentication order

  1. Private key from IdentityFile
  2. SSH agent via SSH_AUTH_SOCK (Unix) or Pageant (Windows)
  3. Password via environment variable SSH_PASSWORD_<HOST>

Example: for host my-server, set SSH_PASSWORD_MY_SERVER=secret.

Why this is better than a plain SSH wrapper

Plain remote exec bridge SSH MCP Server
Often exposes a full shell with little policy control Supports per-host allowlists / denylists
Reconnects for every agent step Reuses pooled connections
Easy to overflow model context with huge outputs Truncates output automatically
Custom host definitions Works with familiar OpenSSH config syntax
Secrets may leak into logs Sanitizes output and hides sensitive values

MCP tools

Tool Description Parameters
ssh_list_hosts List all available SSH hosts —
ssh_exec Execute a command on a remote host host, command, timeout_ms?
ssh_init_config Initialize SSH config file scope, project_root?, hosts?
ssh_get_config Get config for a specific host host
ssh_test_connection Test connectivity to a host host
ssh_disconnect Disconnect one host or all active sessions host?

MCP resources

URI Description
ssh://hosts JSON list of all configured SSH hosts

Security-first defaults

  • Dangerous commands such as rm -rf /, mkfs, dd if=, shutdown, and reboot are blocked by default
  • Private key material and sensitive env values are redacted from outputs
  • Commands are sanitized before execution
  • Concurrent connection count and idle lifetime are limited

Recommended for production:

  1. Prefer IdentityFile over password auth
  2. Use # mcp-ssh:allowlist for production hosts
  3. Add ssh.config to .gitignore if it contains sensitive hostnames
  4. Enable --strict-host-key in production
  5. Use SSH certificates or pinned known_hosts entries when possible

CLI options

ssh-mcp-server [options]

--project-root <path>     Project root directory (for project-level ssh.config)
--user-config <path>      Custom user config path (default: ~/.config/mcp-ssh/config)
--strict-host-key         Enable strict host key checking
--no-strict-host-key      Disable strict host key checking (default)
--timeout <ms>            Default command timeout in ms (default: 60000)
--max-output <chars>      Maximum output characters per stream (default: 10000)
--max-connections <n>     Maximum concurrent SSH connections (default: 5)
--idle-timeout <ms>       Connection idle timeout in ms (default: 600000)

Development

# Install dependencies
npm install

# Run in dev mode
npm run dev -- --project-root .

# Build
npm run build

# Run the built server
npm start -- --project-root .

# Debug with MCP Inspector
npm run inspect

Contributing

Issues and pull requests are welcome. If you want support for more MCP clients, stronger security policies, or better SSH ergonomics, open an issue and share the workflow you want to enable.

For contributor workflow details, see CONTRIBUTING.md.

Community

License

MIT — see LICENSE.