Skip to main content
Glama

SSH MCP Server

by fryjustinc

SSH MCP Server

A Model Context Protocol (MCP) server that gives LLM clients safe, persistent SSH access to remote machines.


Table of Contents

  1. Overview

  2. Key Features

  3. Architecture

  4. Installation

  5. Running the Server

  6. Host Configuration

  7. Session Management

  8. Authentication Modes

  9. Timeouts & Inactivity Handling

  10. Directory Structure

  11. Using the MCP Tools

  12. Testing

  13. Troubleshooting

  14. Security Considerations

  15. Contributing

  16. License


Overview

ssh-mcp lets MCP-compatible clients (such as Claude Code, Cursor, or custom MCP inspectors) control remote machines through SSH. Once hosts are registered, the server maintains persistent shell sessions that retain environment state between commands—ideal for multi-step workflows, long-running processes, or interactive diagnostics.

The server is implemented in TypeScript on top of the official @modelcontextprotocol/sdk.


Key Features

  • MCP-compliant: exposes functionality through standard MCP tool definitions.

  • Persistent sessions: keep shell sessions alive, preserving working directory, environment variables, and process state across multiple commands.

  • Stored host profiles: manage SSH targets through durable JSON configuration (~/.ssh-mcp/hosts.json).

  • Flexible authentication: supports passwords, private keys, and SSH agent forwarding (fallback).

  • Timeout & cleanup safeguards: sessions auto-close after prolonged inactivity; commands are marked and monitored for completion.

  • Structured listings: query active sessions and saved hosts directly from the MCP client.


Architecture

MCP Client ─┬─> add-host / edit-host / remove-host │ ├─> list-hosts │ ├─> start-session ─┬─> PersistentSession (ssh2 shell) │ ├─> exec (reuses shell, captures stdout/stderr) │ └─> close-session / auto-timeout │ └─> list-sessions Persistent configuration → ~/.ssh-mcp/hosts.json

Each active session maintains:

  • SSH connection via ssh2

  • Interactive shell (conn.shell) to support multi-command pipelines

  • Buffered output with unique UUID markers to detect command completion

  • Inactivity timer (defaults to 2 hours)


Installation

git clone https://github.com/tufantunc/ssh-mcp.git cd ssh-mcp npm install npm run build

The build step compiles TypeScript into ./build/index.js and marks it executable.


Running the Server

node build/index.js

The server is purely stdio-based. Once running it prints:

SSH MCP Server running on stdio

You can register it with Claude Code or any other MCP client:

{ "mcpServers": { "mcp-remote-ssh": { "command": "node", "args": [ "/absolute/path/to/ssh-mcp/build/index.js" ] } } }

Note: The server no longer accepts CLI arguments for host/user/password. Everything is configured dynamically via MCP tools.


Host Configuration

Host Storage

  • Hosts are persisted in ~/.ssh-mcp/hosts.json.

  • The directory is created automatically if it does not exist.

  • File format:

{ "hosts": [ { "id": "host", "host": "host.local", "port": 22, "username": "user", "password": "...", // optional "keyPath": "~/.ssh/id_rsa" // optional } ] }

Fields:

  • id (string) — unique identifier used by all session commands.

  • host (string) — hostname or IP.

  • port (number, default 22) — SSH port.

  • username (string) — SSH user.

  • password (optional string) — password auth.

  • keyPath (optional string) — private key path; tilde expansion supported.

    • If neither password nor keyPath is provided, the server attempts to use the local SSH agent via SSH_AUTH_SOCK (with agent forwarding enabled).

The MCP tools ensure this file remains well-formed; never edit it manually unless you know what you’re doing.

Adding Hosts

Tool: add-host

{ "host_id": "user@host.local", "host": "host.local", "port": 22, "username": "user", "password": "optional", "keyPath": "optional" }
  • host_id: new identifier. Must be unique.

  • host: hostname or IP.

  • port: optional (defaults to 22); provide integer > 0.

  • username: SSH user.

  • password or keyPath: optional; configure one or rely on agent.

Example (Claude Code command palette or inspector):

/mcp mcp-remote-ssh add-host {"host_id":"host","host":"host.local","username":"user"}

Listing Hosts

Tool: list-hosts

Returns text with one host per line:

id=host host=host.local:22 user=user auth=agent

auth values:

  • password — password field present

  • key — keyPath present

  • agent — neither password nor keyPath; agent fallback active

Editing Hosts

Tool: edit-host

{ "host_id": "user@host.local", "port": 2222, "password": "new-pass" }

Only supply the properties you want to change. Omitted fields remain unchanged; providing null to a field is not supported—set an empty string or remove the host instead.

Removing Hosts

Tool: remove-host

{ "host_id": "user@host.local" }

Deletes the entry from hosts.json. Active sessions using that host must be closed manually.


Session Management

Starting a Session

Tool: start-session

{ "host_id": "user@host.local" }

Optionally you can supply sessionId; otherwise, a UUID is returned.

Example response:

fff4b34b-56dd-4711-9555-c04e8b64249b

Listing Sessions

Tool: list-sessions

Shows all active sessions with metadata:

session=fff4… host=host.local:22 user=user uptime=3m12s lastCommand=ls -la

Executing Commands

Tool: exec

{ "session_id": "fff4b34b-56dd-4711-9555-c04e8b64249b", "command": "pwd" }
  • Commands are sanitized (trimmed, length-limited).

  • Output is captured from the persistent shell and returned as plain text.

  • Non-zero exit codes raise McpError with stderr in the message.

Example output:

/home/user

Closing Sessions

Tool: close-session

{ "sessionId": "fff4b34b-56dd-4711-9555-c04e8b64249b" }

Note: session IDs for close-session use sessionId (camelCase) to remain backwards compatible with the underlying tool definition.

Legacy Helper

Function execSshCommand(hostId, command, sessionId?) remains exported for programmatic use and simply delegates through the session machinery described above.


Authentication Modes

  1. Password — stored in hosts.json; transmitted to ssh2 during connection.

  2. Private keykeyPath read at runtime; supports encrypted keys (prompt user to set SSH_MCP_KEY_PASSPHRASE before launch if needed).

  3. SSH agent (fallback) — if neither password nor key is set and SSH_AUTH_SOCK is present, the agent is passed to ssh2 (agentForward: true).


Timeouts & Inactivity Handling

  • Each session has a global inactivity timeout (default 2 hours). Timer resets whenever a command executes successfully.

  • If the timer elapses, the session cleans up the SSH connection, shell, and resolver buffer, and removes itself from activeSessions.

  • Command completion uses a UUID marker: printf '__MCP_DONE__{uuid}%d\n' $?. Output before the marker is returned; numeric code after the marker becomes the exit status.


Directory Structure

ssh-mcp/ ├── build/ # Compiled JS output (npm run build) ├── src/index.ts # Primary MCP server implementation ├── test/ # Vitest tests (CLI-only; integration tests skipped) ├── package.json ├── README.md # This document └── ~/.ssh-mcp/hosts.json # Created at runtime (per user)

Using the MCP Tools

Below is a typical workflow using Claude Code (commands start with /mcp), but the same JSON payloads apply to any MCP inspector.

  1. Add host

    /mcp mcp-remote-ssh add-host {"host_id":"host","host":"host.local","username":"user"}
  2. Start session

    /mcp mcp-remote-ssh start-session {"host_id":"host"}

    → returns session_id

  3. Run commands

    /mcp mcp-remote-ssh exec {"session_id":"<id>","command":"pwd"} /mcp mcp-remote-ssh exec {"session_id":"<id>","command":"ls -la"}
  4. Inspect

    /mcp mcp-remote-ssh list-sessions /mcp mcp-remote-ssh list-hosts
  5. Close session

    /mcp mcp-remote-ssh close-session {"sessionId":"<id>"}

Testing

Unit tests (Vitest):

npm run test

Integration smoke tests for SSH are not included by default because they require external infrastructure. You can manually validate with the workflow above.


Troubleshooting

Symptom

Possible Cause

Suggested Action

Host 'xyz' already exists

Duplicate

host_id

Use

edit-host

or pick a new ID.

Host 'xyz' not found

Missing entry

Run

list-hosts

to confirm; add host again if needed.

Error (code X): …

Remote command returned non-zero

Inspect the command output. The session remains open.

Session disappears from

list-sessions

Inactivity timeout reached

Start a new session or reduce idle periods.

Permission denied (publickey)

Missing credentials

Ensure

keyPath

or agent has the right key.

Invalid key path

keyPath

resolved to undefined or missing file

Provide an absolute/tilde path that exists.


Security Considerations

  • Treat ~/.ssh-mcp/hosts.json as sensitive; it may contain passwords or key paths.

  • Prefer key-based or agent authentication where possible.

  • Limit hosts.json permissions: chmod 600 ~/.ssh-mcp/hosts.json.

  • Sessions inherit all privileges of the configured SSH user.

  • Long-running sessions can be closed manually or rely on the inactivity timeout.


Contributing

  1. Fork the repo and create a branch.

  2. Make your changes with tests and documentation updates.

  3. Run npm run build and npm run test before submitting a PR.

  4. Follow the Code of Conduct.

Issues and feature requests are welcome via GitHub.


License

MIT


Happy automating! If this project improves your workflow, please star the repository or share feedback. Your contributions help make remote development safer and simpler for everyone.

-
security - not tested
A
license - permissive license
-
quality - not tested

local-only server

The server can only run on the client's local machine because it depends on local resources.

Provides LLM clients with safe, persistent SSH access to remote machines through the Model Context Protocol. Maintains shell sessions that preserve environment state between commands, enabling multi-step workflows and interactive diagnostics on remote systems.

  1. Table of Contents
    1. Overview
      1. Key Features
        1. Architecture
          1. Installation
            1. Running the Server
              1. Host Configuration
                1. Host Storage
                2. Adding Hosts
                3. Listing Hosts
                4. Editing Hosts
                5. Removing Hosts
              2. Session Management
                1. Starting a Session
                2. Listing Sessions
                3. Executing Commands
                4. Closing Sessions
                5. Legacy Helper
              3. Authentication Modes
                1. Timeouts & Inactivity Handling
                  1. Directory Structure
                    1. Using the MCP Tools
                      1. Testing
                        1. Troubleshooting
                          1. Security Considerations
                            1. Contributing
                              1. License

                                MCP directory API

                                We provide all the information about MCP servers via our MCP API.

                                curl -X GET 'https://glama.ai/api/mcp/v1/servers/fryjustinc/ssh-mcp-sessions'

                                If you have feedback or need assistance with the MCP directory API, please join our Discord server