ssh

This SSH MCP Server allows AI assistants and clients to securely manage remote infrastructure via SSH. It enables executing permitted shell commands on remote hosts, transferring files over SFTP, and establishing SSH tunnels for port forwarding, all within the Model Context Protocol (MCP) framework. Typical use involves running the MCP server through a client (for example via npx or a global npm install) and pointing your MCP client to the server so your AI assistant can issue structured commands that are vetted by the server. Features like granular access control, audit logging, and command templating help keep operations secure and auditable while enabling automation for DevOps workflows.

Available capabilities include:

• Secure SSH Command Execution: run validated shell commands on remote servers with timeouts and safety checks.
• SFTP Integration: read, write, and list files on remote systems without leaving the chat interface.
• Port Forwarding: automatically manage SSH tunnels to access internal services from the AI environment.
• Command Templates: define safe, reusable command macros to standardize common tasks (e.g., logs retrieval, deployments).
• Audit Logging: JSONL trails of all executed commands for compliance and troubleshooting.

To use, configure your MCP client to reference the SSH MCP server (via npx or a global install) and supply a ssh-mcp-config.json describing servers and allowed commands. The server will enforce the configured access rules and provide structured feedback to the AI assistant.

Prerequisites:

• Node.js 18.0.0 or higher
• npm (comes with Node.js)
• SSH access to target servers and private keys configured

Option A: Run via npx (no local install)

• Use the MCP client to load the server via npx as shown in the example configuration.

Option B: Global installation (recommended for persistent use)

1. Install the package globally:

npm install -g @uarlouski/ssh-mcp-server

2. Run the MCP server (or integrate with your MCP client configuration):

# Example: start the server manually (if supported by the package)
ssh-mcp-server --configPath=/path/to/your/ssh-mcp-config.json

3. Create and place your SSH MCP configuration file (ssh-mcp-config.json) at the path you configured, for example:

{
  "allowedCommands": ["ls", "cat", "grep", "docker", "kubectl"],
  "servers": {
    "my-server": {
      "host": "example.com",
      "username": "deploy",
      "privateKeyPath": "~/.ssh/deploy_key"
    }
  }
}

4. Update your MCP client configuration to point to the SSH MCP server, for example using npx as shown in the README:

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": [
        "@uarlouski/ssh-mcp-server@latest",
        "--configPath=/Users/yourname/ssh-mcp-config.json"
      ]
    }
  }
}

Tips and notes:

• If you already maintain an SSH config (~/.ssh/config), you can enable SSH config import to reuse existing host definitions.
• Use allowedCommands to enforce strict validation, restricting the base commands and their arguments to prevent unsafe actions. This helps protect against command injection from AI prompts.
• You can define complex command templates (macros) for common tasks, such as retrieving logs, patching configs, or deploying apps, while keeping user input safe.
• Configure portForwardingServices to expose internal services securely via tunnels when needed.
• Ensure proper key-based authentication (Ed25519/RSA) and rotate keys regularly for security.
• Review the audit logs (JSONL) to monitor activity and support compliance reviews.
• If you need to migrate from an existing setup, leverage the sshConfigImport option to pull hosts from ~/.ssh/config and minimize configuration drift.