Simple SSH MCP Server

A tiny MCP server for SSH with persistent sessions.

This project is intentionally simple: it works, it fits my day-to-day workflow, and that is the main goal.

🤝 Why This Exists

I wanted a lightweight SSH MCP setup that:

• keeps one SSH session alive across tool calls
• reads host credentials from a config file
• stays easy to understand and tweak

If you are looking for a big roadmap or tons of features, this is probably not that project. That said, contributions are welcome.

✨ Features

• Persistent SSH session: connection stays alive between ssh_execute calls
• Session state preserved: cd, env vars, and shell state carry over
• Config-driven hosts: no passing host/password/private key on every call
• Multiple hosts: switch by hostName
• Idle cleanup: sessions auto-disconnect after timeout
• Raw output option: inspect full terminal output with showRaw

🚀 Quick Start

Main guide uses pnpm.

pnpm install
pnpm build
cp config.example.json config.json

Edit config.json and add your hosts.

If you are still using npm, no judgment... but pnpm is faster and your SSD will thank you.

npm (alternative)

npm install
npm run build
cp config.example.json config.json

⚙️ Config File

Example:

{
  "hosts": {
    "my-server": {
      "host": "192.168.1.100",
      "port": 22,
      "username": "admin",
      "password": "your-password"
    },
    "dev-server": {
      "host": "dev.example.com",
      "username": "developer",
      "privateKeyPath": "~/.ssh/id_rsa"
    }
  },
  "settings": {
    "sessionTimeoutMinutes": 10,
    "commandTimeoutSeconds": 30,
    "defaultPort": 22
  }
}

Config Lookup Order

The server checks config paths in this order:

1. --config <path> or -c <path>
2. SSH_MCP_CONFIG_PATH
3. ./config.json
4. ~/.ssh-mcp-server/config.json

Auth Options

• password
• privateKeyPath (supports ~)
• passphrase (optional, for encrypted keys)

🧭 Cursor Setup

Add this to Cursor MCP settings:

{
  "mcpServers": {
    "simple-ssh": {
      "command": "node",
      "args": [
        "/absolute/path/to/my-ssh-mcp-server/dist/index.js",
        "--config",
        "/absolute/path/to/my-ssh-mcp-server/config.json"
      ]
    }
  }
}

🖥️ Claude Desktop Setup

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "simple-ssh": {
      "command": "node",
      "args": [
        "/absolute/path/to/my-ssh-mcp-server/dist/index.js",
        "--config",
        "/absolute/path/to/my-ssh-mcp-server/config.json"
      ]
    }
  }
}

🧰 Available Tools

ssh_list_hosts

List configured hosts.

ssh_connect

Connect to a host from config.

Parameters:

• hostName (required)
• sessionId (optional)

ssh_execute

Run a command in an existing session.

Parameters:

• sessionId (required)
• command (required)
• timeout (optional, seconds)
• showRaw (optional, boolean; include raw terminal output)

ssh_list_sessions

List active sessions.

ssh_disconnect

Disconnect a session.

Parameters:

• sessionId (required)

🧪 Example Usage

1. ssh_list_hosts
2. ssh_connect({ hostName: "my-server" })
3. ssh_execute({ sessionId: "...", command: "cd /var/log" })
4. ssh_execute({ sessionId: "...", command: "ls -la" })
5. ssh_disconnect({ sessionId: "..." })

🛠️ Development

pnpm dev
pnpm build
pnpm start

npm (alternative)

npm run dev
npm run build
npm start

🔐 Security Notes

• config.json has secrets and is ignored by git
• do not commit real credentials
• sessions auto-expire after idle timeout

📄 License

This project is released under The Unlicense.