HydroSSH

中文 | English | Configuration Guide | 配置指南

MCP server that provides SSH remote connection capabilities for Claude Code. Connect to remote servers, execute commands, and automate deployments without needing a separate SSH terminal.

npm version License: MIT

---

Part 1: Features

What is this?

mcp-hydrocoder-ssh is an MCP (Model Context Protocol) server that enables Claude Code to:

• 🔌 Connect to remote SSH servers directly (persistent background connections)
• ⚡ Execute commands and get complete output
• 🔄 Maintain connection state for multi-step operations
• 🚀 Run deployment scripts (git pull, npm install, systemctl restart, etc.)

Key Benefits

Benefit	Description
No window switching	Complete all remote operations within Claude Code conversation
Smart deployment	Claude can auto-determine next steps based on command output
Multi-server management	Manage multiple server configs, switch quickly
Secure authentication	Support SSH agent, key files
Connection pooling	Maintain persistent connections, avoid re-authentication overhead

Available Tools

SSH Connection Tools (5):

• ssh_list_servers - List all configured servers
• ssh_connect - Connect to a server
• ssh_exec - Execute commands (with working directory support)
• ssh_get_status - Get connection status
• ssh_disconnect - Disconnect from server

Configuration Management Tools (5):

• ssh_add_server - Add new server configuration
• ssh_remove_server - Remove server configuration
• ssh_update_server - Update server configuration
• ssh_view_config - View config (filters sensitive info)
• ssh_help - Show help information

---

Part 2: Installation

Option 1: Global Install + User-Level Config (Recommended)

npm install -g mcp-hydrocoder-ssh
claude mcp add -s user hydrossh mcp-hydrocoder-ssh

Option 2: Global Install + Project-Level Config

npm install -g mcp-hydrocoder-ssh
claude mcp add hydrossh mcp-hydrocoder-ssh

Option 3: npx Install + User-Level Config

claude mcp add -s user hydrossh npx mcp-hydrocoder-ssh@latest

Option 4: npx Install + Project-Level Config

claude mcp add hydrossh npx mcp-hydrocoder-ssh@latest

Notes:

• -s user flag sets user-level MCP configuration, available to all projects
• Without -s user, configuration is project-level, only available to current project
• Using npx does not require pre-installing the npm package

Verify Installation

In Claude Code, enter:

List available SSH servers

If you see a server list (empty list means no servers configured yet), the installation was successful.

---

Part 3: Using from Source Code

1. Clone Repository

git clone https://github.com/hydroCoderClaud/mcpHydroSSH.git
cd mcpHydroSSH

2. Install Dependencies

npm install

3. Build

npm run build

Build output goes to dist/ directory:

• dist/index.js - MCP server entry point
• dist/ssh-manager.js - SSH connection management
• dist/config.js - Configuration management

4. Configure Claude Code

Edit ~/.claude.json:

{
  "mcpServers": {
    "hydrossh": {
      "command": "node",
      "args": ["<absolute-path>/dist/index.js"]
    }
  }
}

Note: Replace <absolute-path> with your actual source directory absolute path.

5. Restart Claude Code

Close and reopen Claude Code.

6. Development Mode (Optional)

For hot-reload development:

npm run dev

Then configure Claude Code with:

{
  "mcpServers": {
    "hydrossh": {
      "command": "npx",
      "args": ["tsx", "<absolute-path>/src/index.ts"]
    }
  }
}

---

Appendix A: SSH Configuration

Configuration file location: ~/.hydrossh/config.json

Auto-created on first run: The ~/.hydrossh/ directory and config file are automatically created when the MCP server first starts.

Quick Add via Claude Code

After installation, you can add server configs using natural language commands.

Configuration Example

{
  "servers": [
    {
      "id": "prod-server",
      "name": "Production Server",
      "host": "example.com",
      "port": 22,
      "username": "deploy",
      "authMethod": "agent"
    },
    {
      "id": "test-server",
      "name": "Test Server",
      "host": "test.example.com",
      "username": "ubuntu",
      "authMethod": "key",
      "privateKeyPath": "~/.ssh/id_rsa"
    }
  ],
  "settings": {
    "defaultConnectTimeout": 30000,
    "defaultKeepaliveInterval": 60000,
    "commandTimeout": 60000,
    "maxConnections": 5,
    "logCommands": true
  }
}

Authentication Methods

Method	Configuration	Description
SSH Agent	"authMethod": "agent"	Recommended, uses system SSH agent
Key File	"authMethod": "key", "privateKeyPath": "~/.ssh/id_rsa"	Default, reads private key file
Password	"authMethod": "password", "password": "xxx"	Not recommended, password stored in plaintext

See CONFIG-GUIDE_EN.md for details.

---

Appendix B: Usage Examples

Basic Usage

User: List available servers
Claude: Found 2 configured servers: prod-server, test-server

User: Connect to prod-server
Claude: [ssh_connect] Connected! connectionId: xxx

User: Execute command: uptime
Claude: [ssh_exec] Returns: up 30 days, 2 users, load average: 0.1, 0.2, 0.5

User: Disconnect
Claude: [ssh_disconnect] Disconnected

Automated Deployment

User: Deploy latest code to production server
Claude: Okay, I'll execute the deployment flow...
1. Connect to prod-server
2. cd /opt/myapp && git pull
3. npm ci --production
4. sudo systemctl restart myapp
5. Check service status
6. Disconnect
Deployment complete!

---

Appendix C: Security Notes

• 🔒 SSH Agent Recommended - Prefer authMethod: "agent"
• 🔒 Config File Permissions - Ensure ~/.hydrossh/config.json is readable only by you
• 🔒 Config Viewing - ssh_view_config tool automatically filters passwords and key paths

---

Appendix D: Troubleshooting

Issue	Solution
SSH Agent not running	Windows: Start "OpenSSH Authentication Agent" service
Connection timeout	Check server address, port, network connectivity
Command not found	Verify npm global install or check PATH environment variable
Config not loaded	Check if ~/.claude.json format is correct
Config file not found	Auto-created on first run, or manually create ~/.hydrossh/config.json

---

Appendix E: Command Reference

Development Commands

npm run build        # Build TypeScript
npm run dev          # Development mode (hot reload)
npm test             # Run tests
npm run lint         # Code linting
npm run format       # Code formatting

MCP Tool Parameters

Tool	Parameters	Description
ssh_list_servers	none	List all configured servers
ssh_connect	serverId, timeout?	Connect to server
ssh_exec	command, connectionId?, timeout?, cwd?	Execute command
ssh_get_status	connectionId?	Get connection status (all if not specified)
ssh_disconnect	connectionId?	Disconnect (most recent if not specified)
ssh_add_server	id, name, host, username, port?, authMethod?, privateKeyPath?, password?	Add server config
ssh_remove_server	serverId	Remove server config
ssh_update_server	serverId, name?, host?, port?, username?, authMethod?, privateKeyPath?, password?	Update server config
ssh_view_config	none	View config (filters sensitive info)
ssh_help	topic?	Show help information

---

License

MIT