mcpHydroSSH MCP Server

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.

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

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"
    }