SSH MCP Server

SSH MCP Server

A Model Context Protocol (MCP) server implementation that provides SSH capabilities. This server allows for secure remote access and execution through the MCP protocol.

Features

• SSH server implementation using MCP protocol
• SQLite database integration for data persistence
• TypeScript implementation for type safety and better development experience

Prerequisites

• Node.js 18 or higher
• npm or yarn package manager
• TypeScript knowledge for development

Installation

Installing via Smithery

To install SSH Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @KinoThe-Kafkaesque/ssh-mcp-server --client claude

Manual Installation

1. Clone the repository:

git clone <repository-url>
cd ssh-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Usage

Configuration

The server uses a SQLite database (ssh.db) to store SSH credentials. The database file will be created automatically when the server starts.

Tools

The server stores named credentials, then every remote action refers to a credentialName. privateKeyPath must point to an existing private key (~/ expands to your home directory).

Host keys are verified: the first time a credential connects, the server's host key fingerprint is pinned in ~/ssh.db. Later connections that present a different key are refused with HOST_KEY_MISMATCH. To pin a known key up front, pass hostKeyFingerprint (the SHA256:... value printed by ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub on the server). After a legitimate key change, remove the credential and add it again.

• add_credential: save { "name", "host", "username", "privateKeyPath", "hostKeyFingerprint"? }.
• list_credentials: list stored credential records.
• remove_credential: delete { "name" }.
• ssh_exec: run a shell command with { "credentialName", "command", "timeout" }.
• ssh_exec_raw: run an argv-style command array, for example { "credentialName": "prod", "command": ["grep", "-E", "foo|bar", "/var/log/app.log"] }.
• scp_copy: copy one file over SFTP with { "credentialName", "localPath", "remotePath", "direction" }.
• rsync_copy: copy directories or larger trees with rsync and the same transfer shape.
• ssh_session_start, ssh_session_send, ssh_session_read, ssh_session_end, ssh_session_list: manage interactive SSH sessions.
• ssh_tunnel_start, ssh_tunnel_list, ssh_tunnel_stop: manage local or remote port-forwarding tunnels.

Example:

{
  "tool_name": "ssh_exec",
  "arguments": {
    "credentialName": "prod",
    "command": "uptime",
    "timeout": 120000
  }
}

Starting the server

npm start

The server will start running on the configured port (default settings can be modified in the source code).

CLI Usage

The CLI shares the MCP server's ~/ssh.db credential store. For remote work it uses an OpenSSH multiplexed connection, so separate CLI invocations for the same host, username, and key reuse one authenticated transport. Build first, then run with npm run cli -- or via the sshcli bin after npm link:

npm run build && npm run cli -- <command>
# or, after linking:
npx sshcli <command>

Commands:

sshcli creds add prod --host 1.2.3.4 --user ubuntu --key ~/.ssh/id_rsa
sshcli creds list
sshcli creds rm prod
sshcli exec prod uptime
sshcli exec prod --timeout 30000 -- df -h /
sshcli exec --raw prod grep -E 'foo|bar' /var/log/app.log
sshcli scp prod ./file.txt /tmp/file.txt toRemote
sshcli rsync prod ./dir/ /tmp/dir/ fromRemote
sshcli session prod   # live interactive shell; Ctrl+D or exit to close
sshcli tunnel prod --type local --local-port 8080 --remote-host localhost --remote-port 80
sshcli cache status prod
sshcli cache close prod

Notes:

• For exec, the variadic <command...> is greedy, so put options like --timeout and --raw before the command tokens.
• exec, scp, rsync, session, and tunnel all reuse the same connection. Idle connections remain cached for 30 minutes by default.
• The first connection attempt for an endpoint is serialized across CLI processes. A failed attempt creates a 15-second exponential reconnect backoff (up to 5 minutes), preventing repeated calls from hammering a rate-limited host.
• session and tunnel are foreground commands that block until the shell closes or you press Ctrl+C, respectively; exiting them does not close the shared transport.
• The CLI intentionally omits session send/read/end/list and tunnel list/stop commands: their in-memory state does not persist across one-shot CLI invocations. Use the foreground session and tunnel commands instead.
• The cache lives under $XDG_RUNTIME_DIR/sshcli/connections (or a private per-user temporary directory). Tune it with SSHCLI_CONTROL_PERSIST_SECONDS, SSHCLI_RECONNECT_BACKOFF_MS, SSHCLI_RECONNECT_BACKOFF_MAX_MS, or SSHCLI_CACHE_DIR.
• OpenSSH, scp, and rsync must be available in PATH for their corresponding CLI commands.

Project Structure

• src/ - Source code directory
• build/ - Compiled JavaScript output
• node_modules/ - Project dependencies

Dependencies

• @modelcontextprotocol/sdk: MCP protocol implementation
• sqlite3: SQLite database driver
• typescript: Development dependency for TypeScript support

Development

To make changes to the project:

1. Make your changes in the src/ directory
2. Rebuild the project:

npm run build

3. Start the server to test your changes:

npm start

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request