McpHydroSSH

mcp-hydrocoder-ssh

中文 | 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.

[](https://www.npmjs.com/package/mcp-hydrocoder-ssh) [](https://opensource.org/licenses/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": ["/dist/index.js"]
    }
  }
}

> Note: Replace `` 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", "/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-GUIDEEN.md](CONFIG-GUIDEEN.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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hydroCoderClaud
• Source: hydroCoderClaud/mcpHydroSSH
• License: MIT

Install and usage instructions live in the source repository linked above.