wiki/ssh-mcp/INSTALLATION.md

← Home

Installation Guide

---

Prerequisites

Requirement	Minimum Version	Notes
Node.js	18.0.0	LTS recommended
npm	9.x	Ships with Node.js 18+
SSH key pair	--	Ed25519 recommended (ssh-keygen -t ed25519)
rsync	--	Required only for ssh_sync
sshpass	--	Required only for ssh_sync with password auth

Generating an SSH Key

If you do not already have an SSH key:

ssh-keygen -t ed25519 -C "your_email@example.com"

Copy the public key to each remote server:

ssh-copy-id -i ~/.ssh/id_ed25519.pub user@host

---

Install

Clone the repository and install dependencies:

git clone https://git.mokoconsulting.tech/MokoConsulting/ssh-mcp.git
cd ssh-mcp
npm install

---

Configuration

ssh-mcp reads server definitions from environment variables. The recommended approach is a .env file stored at ~/.ssh-manager/.env.

.env File Search Order

The server searches for .env in this order:

Priority	Location	Description
1	SSH_ENV_PATH environment variable	Explicit override
2	~/.ssh-manager/.env	User config directory
3	<cwd>/.env	Current working directory
4	~/.env	Home directory
5	<install-dir>/.env	Backward compatibility

.env Format

Each server is defined by a set of variables sharing a common name prefix. The name is case-insensitive and is used to reference the server in tool calls.

# --- Required ---
SSH_SERVER_PRODUCTION_HOST=192.168.1.100
SSH_SERVER_PRODUCTION_USER=deploy

# --- Authentication (pick one) ---
SSH_SERVER_PRODUCTION_KEYPATH=~/.ssh/id_ed25519
# or
SSH_SERVER_PRODUCTION_PASSWORD=s3cret

# --- Optional ---
SSH_SERVER_PRODUCTION_PASSPHRASE=key_passphrase
SSH_SERVER_PRODUCTION_PORT=22
SSH_SERVER_PRODUCTION_DEFAULT_DIR=/var/www/myapp
SSH_SERVER_PRODUCTION_SUDO_PASSWORD=sudopass
SSH_SERVER_PRODUCTION_PLATFORM=linux           # "linux" (default) or "windows"
SSH_SERVER_PRODUCTION_PROXYJUMP=bastion         # Name of another configured server
SSH_SERVER_PRODUCTION_PROXYCOMMAND=ncat --proxy 127.0.0.1:1080 --proxy-type socks5 %h %p

Field Reference

Field	Required	Description
HOST	Yes	Hostname or IP address
USER	Yes	SSH username
PASSWORD	Auth	Password for password-based authentication
KEYPATH	Auth	Path to SSH private key file
PASSPHRASE	No	Passphrase for encrypted private keys
PORT	No	SSH port (default: 22)
DEFAULT_DIR	No	Default working directory for commands
SUDO_PASSWORD	No	Password for sudo operations
PLATFORM	No	linux (default) or windows
PROXYJUMP	No	Name of a configured server to use as a jump host
PROXYCOMMAND	No	Custom proxy command (supports %h and %p placeholders)

TOML Format (Alternative)

ssh-mcp also supports TOML configuration, useful for OpenAI Codex integration. Place the file at ~/.codex/ssh-config.toml or set SSH_CONFIG_PATH:

[ssh_servers.production]
host = "192.168.1.100"
user = "deploy"
key_path = "~/.ssh/id_ed25519"
port = 22
default_dir = "/var/www/myapp"

Set PREFER_TOML_CONFIG=true to prefer TOML over .env when both exist.

---

Claude Code Registration

Register the MCP server with Claude Code:

claude mcp add ssh-manager node /absolute/path/to/ssh-mcp/src/index.js

The configuration is stored in ~/.config/claude-code/claude_code_config.json.

After registration, Claude Code will list the ssh-mcp tools automatically. You can verify by asking Claude Code to run ssh_list_servers.

---

Multiple Server Setup

Define as many servers as you need by repeating the variable block with different names:

# Production
SSH_SERVER_PRODUCTION_HOST=prod.example.com
SSH_SERVER_PRODUCTION_USER=deploy
SSH_SERVER_PRODUCTION_KEYPATH=~/.ssh/id_ed25519

# Staging
SSH_SERVER_STAGING_HOST=staging.example.com
SSH_SERVER_STAGING_USER=deploy
SSH_SERVER_STAGING_KEYPATH=~/.ssh/id_ed25519

# Database server
SSH_SERVER_DB_HOST=db.internal
SSH_SERVER_DB_USER=dba
SSH_SERVER_DB_KEYPATH=~/.ssh/id_ed25519
SSH_SERVER_DB_DEFAULT_DIR=/var/lib/mysql

# Bastion / jump host
SSH_SERVER_BASTION_HOST=bastion.example.com
SSH_SERVER_BASTION_USER=admin
SSH_SERVER_BASTION_KEYPATH=~/.ssh/id_ed25519

# Server behind bastion
SSH_SERVER_INTERNAL_HOST=10.0.0.5
SSH_SERVER_INTERNAL_USER=deploy
SSH_SERVER_INTERNAL_KEYPATH=~/.ssh/id_ed25519
SSH_SERVER_INTERNAL_PROXYJUMP=bastion

Server Groups

After defining servers, you can organize them into groups using the ssh_group_manage tool:

ssh_group_manage action=create name=web-servers servers=["production","staging"]

Then execute commands across the group:

ssh_execute_group group=web-servers command="uptime"

---

Tool Management

By default all 37 tools are enabled. To reduce context usage in Claude Code, use the CLI to disable groups you do not need:

ssh-manager tools configure      # Interactive wizard
ssh-manager tools disable monitoring
ssh-manager tools disable database
ssh-manager tools list           # Verify

See Tool Management for details.

---

Development Setup

Install pre-commit hooks for secret scanning:

./scripts/setup-hooks.sh

Run tests:

npm test

Run the validation suite:

./scripts/validate.sh

---

Troubleshooting

"Server not found" errors

• Server names are case-insensitive. PRODUCTION, production, and Production all resolve to the same entry.
• Verify the .env file is in one of the searched locations (see table above).
• Run ssh_list_servers to see which servers are loaded.

Connection timeouts

• Check that the remote host is reachable: ssh -v user@host
• Ensure port 22 (or your custom port) is open in firewalls.
• Idle connections are closed after 30 minutes. The server will reconnect automatically on the next tool call.

Permission denied (publickey)

• Confirm the key path in KEYPATH points to the correct private key.
• Verify the public key is in ~/.ssh/authorized_keys on the remote server.
• Check key file permissions: chmod 600 ~/.ssh/id_ed25519

rsync / ssh_sync failures

• ssh_sync requires rsync installed on both local and remote machines.
• Password-based auth additionally requires sshpass on the local machine.

Host key verification failed

• Use ssh_key_manage action=verify server=name to inspect the key.
• If the server was reinstalled, use ssh_key_manage action=accept server=name to trust the new key.

Logs

Set SSH_LOG_LEVEL=DEBUG in your environment for verbose logging. Logs are written to stderr.

SSH_LOG_LEVEL=DEBUG node src/index.js 2>debug.log

---

Repo: ssh-mcp · MokoStandards

Revision	Date	Author	Description
1.0	2026-05-09	Moko Consulting	Initial version