SSH MCP Server

A Model Context Protocol (MCP) server that enables Claude Code to execute commands on remote servers via SSH. Supports both password and private key authentication.

Features

• Execute remote commands via SSH
• Password authentication
• Private key authentication (with optional passphrase)
• Configurable timeouts
• Structured output with stdout, stderr, and exit codes

Installation

npm install -g @davidfei/ssh-mcp

Usage with Claude Code

After installation, configure the MCP server in your Claude Code settings:

{
  "mcpServers": {
    "ssh": {
      "command": "ssh-mcp"
    }
  }
}

Restart Claude Code to load the server.

Authentication Methods

Claude Code can use the ssh_exec tool with the following authentication methods:

Password Authentication

Ask Claude Code to execute a command like:

Connect to example.com as user with password authentication and run: ls -la

Private Key Authentication (file path)

Ask Claude Code to:

Connect to example.com using SSH key at ~/.ssh/id_rsa and run: df -h

Private Key with Passphrase

Ask Claude Code to:

Connect to example.com using encrypted SSH key at ~/.ssh/id_rsa with passphrase and run: uname -a

Tool Reference

ssh_exec

Execute a command on a remote server via SSH.

Parameters:

• connection (object, required):

  • host (string, required): SSH server hostname or IP address
  • port (number, optional): SSH server port (default: 22)
  • username (string, required): SSH username
  • password (string, optional): SSH password for password authentication
  • privateKey (string, optional): SSH private key content for key-based authentication
  • privateKeyPath (string, optional): Path to SSH private key file
  • passphrase (string, optional): Passphrase for encrypted private key

• command (string, required): Command to execute on the remote server

• timeout (number, optional): Command timeout in milliseconds (default: 30000)

Response:

{
  "success": true,
  "stdout": "command output",
  "stderr": "",
  "exitCode": 0
}

Example Commands

Ask Claude Code to:

• "Check disk usage on production server at 192.168.1.100"
• "Run the backup script on remote-server.com"
• "Check system information on my-server"
• "List running Docker containers on the deployment server"

Security Considerations

• Store credentials securely (use environment variables or secure vaults)
• Use private key authentication when possible
• Limit SSH user permissions on remote servers
• Use firewall rules to restrict SSH access
• Consider using SSH certificates for enhanced security
• Avoid hardcoding credentials in configuration files

Troubleshooting

Connection timeout

Increase the timeout parameter or check network connectivity:

{
  "timeout": 60000
}

Authentication failed

• Verify username and password/key are correct
• Check SSH server allows the authentication method
• Ensure private key has correct permissions (600)
• Verify the private key format is supported

Command not found

Ensure the command exists on the remote server and is in the PATH.

Requirements

• Node.js >= 18.0.0
• SSH access to remote servers
• Claude Code installation

Development

For local development and contributing, see DEVELOPMENT.md.

License

MIT

Support

For issues and questions, please open an issue on the GitHub repository.