{"_id":"@hbarhate/ssh-mcp-server","name":"@hbarhate/ssh-mcp-server","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@hbarhate/ssh-mcp-server","version":"0.1.0","description":"MCP server for SSH remote command execution","main":"dist/index.js","type":"module","bin":{"ssh-mcp-server":"dist/index.js"},"scripts":{"build":"tsc && npm run postbuild","postbuild":"node -e \"require('fs').mkdirSync('dist/scripts', {recursive: true}); require('fs').copyFileSync('scripts/ssh-approval.vbs', 'dist/scripts/ssh-approval.vbs')\"","start":"node dist/index.js","dev":"tsx src/index.ts","encrypt-password":"tsx scripts/encrypt-password.ts","prepublishOnly":"npm run build","test":"tsx --test tests/*.test.ts","test:host-generator":"tsx --test tests/host-generator.test.ts","test:host-config":"tsx --test tests/host-config.test.ts","test:crypto":"tsx --test tests/crypto-utils.test.ts","test:config":"tsx --test tests/config.test.ts","test:logger":"tsx --test tests/logger.test.ts","test:schemas":"tsx --test tests/tool-schemas.test.ts","test:ssh-manager":"tsx --test tests/ssh-manager.test.ts","test:e2e":"tsx --test tests/e2e.test.ts"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","dotenv":"^16.6.1","node-ssh":"^13.2.0","ssh2":"^1.15.0"},"devDependencies":{"@types/node":"^20.0.0","@types/ssh2":"^1.15.5","tsx":"^4.0.0","typescript":"^5.0.0"},"keywords":["mcp","ssh","remote","command","model-context-protocol","mcp-server"],"author":{"name":"hbarhate"},"license":"MIT","engines":{"node":">=18.0.0"},"types":"./dist/index.d.ts","_id":"@hbarhate/ssh-mcp-server@0.1.0","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-bolW8qR8xw5Ta5J31mUhNqfNAdyckhI1rD8bPBEyizzuXo/bs1XITR5GoZiyHwY4lc4CAg5ElRATx7Qe3KIB3A==","shasum":"2dda2804d7474d7ba6a3408ab4cd099ba14fc0c0","tarball":"https://registry.npmjs.org/@hbarhate/ssh-mcp-server/-/ssh-mcp-server-0.1.0.tgz","fileCount":44,"unpackedSize":119167,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDVETgngAbAYRNTLHt2MaF6PyAXz2BHq96hKtu2GX6zEAiEAtqbWT2mt9xYBeh+cXP+431LDCwovawgcgFZbRxq1Cck="}]},"_npmUser":{"name":"hbarhate","email":"hbarhate2002@gmail.com"},"directories":{},"maintainers":[{"name":"hbarhate","email":"hbarhate2002@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ssh-mcp-server_0.1.0_1778067695219_0.25501223678712925"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-06T11:41:35.102Z","0.1.0":"2026-05-06T11:41:35.362Z","modified":"2026-05-06T11:41:35.563Z"},"maintainers":[{"name":"hbarhate","email":"hbarhate2002@gmail.com"}],"description":"MCP server for SSH remote command execution","keywords":["mcp","ssh","remote","command","model-context-protocol","mcp-server"],"author":{"name":"hbarhate"},"license":"MIT","readme":"# SSH MCP Server\n\n[![npm version](https://img.shields.io/npm/v/@hbarhate/ssh-mcp-server.svg)](https://www.npmjs.com/package/@hbarhate/ssh-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n\nA Model Context Protocol (MCP) server for executing commands on remote servers via SSH, built with TypeScript and Node.js. Provides comprehensive tools for SSH command execution, Kubernetes management, and connection pooling.\n\n## Features\n\n- **Dual Authentication** - SSH key and password authentication support\n- **8 MCP Tools** - Complete coverage of SSH operations\n- **Persistent Connections** - Efficient connection pooling and reuse\n- **Host Aliases** - Pre-configure named hosts with connection details\n- **Command Confirmation** - Layered approval system for safe execution\n- **Kubernetes Support** - Specialized kubectl command execution\n- **Batch Execution** - Run up to 5 commands in parallel\n- **TypeScript** - Full type safety and modern ES modules\n\n## Installation\n\n### Using npm (Global)\n\n```bash\nnpm install -g @hbarhate/ssh-mcp-server\n```\n\n### Using npx (No Installation)\n\n```bash\nnpx @hbarhate/ssh-mcp-server\n```\n\n## Updating\n\n### Update Global Installation\n\n```bash\nnpm update -g @hbarhate/ssh-mcp-server\n```\n\n### Update to Latest with npx\n\n```bash\nnpx @hbarhate/ssh-mcp-server@latest\n```\n\n### Check Current Version\n\n```bash\nnpm list -g @hbarhate/ssh-mcp-server\n```\n\n## Configuration\n\nConfigure the server using environment variables or configuration files.\n\n### Environment Variables\n\n```bash\nexport MCP_APP_CONFIG_PATH=\"/path/to/app.config.json\"\nexport MCP_HOSTS_CONFIG_PATH=\"/path/to/hosts.json\"\nexport SSH_PASSWORD_MYUSER=\"<encrypted-password>\"\n```\n\n| Variable                 | Description                                                                 |\n| ------------------------ | --------------------------------------------------------------------------- |\n| `MCP_APP_CONFIG_PATH`    | Path to `app.config.json` (defaults to `./app.config.json`)                 |\n| `MCP_HOSTS_CONFIG_PATH`  | Path to `hosts.json` (defaults to `./hosts.json`)                           |\n| `SSH_PASSWORD_<USER>`    | Encrypted password for SSH authentication (e.g., `SSH_PASSWORD_MYUSER`)     |\n\n### App Configuration File\n\nCreate `app.config.json` in your project directory:\n\n```json\n{\n  \"defaultUser\": \"myuser\",\n  \"defaultAuthType\": \"password\",\n  \"sshPasswordEnvVar\": \"SSH_PASSWORD_MYUSER\",\n  \"askUserApproval\": true,\n  \"connectionTimeout\": 30000,\n  \"healthCheckInterval\": 60000\n}\n```\n\n### Host Configuration File\n\nCreate `hosts.json` to define host aliases:\n\n```json\n{\n  \"hosts\": {\n    \"k8s-prod\": {\n      \"host\": \"kubemaster01.prod.example.com\",\n      \"user\": \"myuser\",\n      \"authType\": \"password\",\n      \"description\": \"Kubernetes master production\"\n    },\n    \"jumpbox\": {\n      \"host\": \"10.0.1.100\",\n      \"user\": \"ubuntu\",\n      \"authType\": \"key\",\n      \"keyPath\": \"~/.ssh/jumpbox_rsa\",\n      \"description\": \"Jump server\"\n    }\n  }\n}\n```\n\n### MCP Client Configuration\n\nAdd to your MCP client config (e.g., Claude Desktop, Windsurf):\n\n```json\n{\n  \"mcpServers\": {\n    \"ssh-mcp-server\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/ssh-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"MCP_APP_CONFIG_PATH\": \"/path/to/app.config.json\",\n        \"MCP_HOSTS_CONFIG_PATH\": \"/path/to/hosts.json\",\n        \"SSH_PASSWORD_MYUSER\": \"<encrypted-password>\"\n      }\n    }\n  }\n}\n```\n\n## Tools Reference\n\n### SSH Execution\n\n| Tool                        | Description                              | Parameters                                                                                          |\n| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------- |\n| `ssh_execute`               | Execute command on remote server         | `host`, `command`, `dryRun?`, `user?`, `authType?`, `password?`, `keyPath?`, `passphrase?`          |\n| `ssh_execute_batch`         | Execute up to 5 commands in parallel     | `executions` (array of execution objects)                                                           |\n| `ssh_kubectl`               | Execute kubectl on kubemaster nodes      | `pod`, `region`, `command`, `user?`                                                                 |\n\n### Connection Management\n\n| Tool                        | Description                              | Parameters                                                                                          |\n| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------- |\n| `ssh_connection_status`     | Get status of persistent connections     | -                                                                                                   |\n| `ssh_close_connection`      | Close a specific SSH connection          | `host`, `user?`                                                                                     |\n| `ssh_close_all_connections` | Close all persistent connections         | -                                                                                                   |\n\n### Host Management\n\n| Tool                        | Description                              | Parameters                                                                                          |\n| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------- |\n| `ssh_list_hosts`            | List all configured host aliases         | -                                                                                                   |\n| `generate_hosts`            | Generate hostnames based on patterns     | `nodeType`, `pod`, `region`, `count?`                                                               |\n\n## Usage Examples\n\n### Execute Remote Command\n\n```json\n{\n  \"tool\": \"ssh_execute\",\n  \"arguments\": {\n    \"host\": \"k8s-prod\",\n    \"command\": \"uptime\"\n  }\n}\n```\n\n### Execute with Full Hostname\n\n```json\n{\n  \"tool\": \"ssh_execute\",\n  \"arguments\": {\n    \"host\": \"kubemaster01.prod.example.com\",\n    \"command\": \"ls -la /var/log\",\n    \"user\": \"admin\"\n  }\n}\n```\n\n### Dry Run Preview\n\n```json\n{\n  \"tool\": \"ssh_execute\",\n  \"arguments\": {\n    \"host\": \"k8s-prod\",\n    \"command\": \"rm -rf /tmp/logs\",\n    \"dryRun\": true\n  }\n}\n```\n\n### Kubernetes Command\n\n```json\n{\n  \"tool\": \"ssh_kubectl\",\n  \"arguments\": {\n    \"pod\": \"prod\",\n    \"region\": \"us-east\",\n    \"command\": \"get pods --all-namespaces\"\n  }\n}\n```\n\n### Batch Parallel Execution\n\n```json\n{\n  \"tool\": \"ssh_execute_batch\",\n  \"arguments\": {\n    \"executions\": [\n      {\n        \"host\": \"kubemaster01.prod.example.com\",\n        \"command\": \"uptime\"\n      },\n      {\n        \"host\": \"kubemaster02.prod.example.com\",\n        \"command\": \"uptime\"\n      },\n      {\n        \"host\": \"kubemaster03.prod.example.com\",\n        \"command\": \"uptime\"\n      }\n    ]\n  }\n}\n```\n\n### Generate Hostnames\n\n```json\n{\n  \"tool\": \"generate_hosts\",\n  \"arguments\": {\n    \"nodeType\": \"kubenode\",\n    \"pod\": \"prod\",\n    \"region\": \"us-east\",\n    \"count\": 5\n  }\n}\n```\n\n### Connection Management\n\n```json\n{\n  \"tool\": \"ssh_connection_status\",\n  \"arguments\": {}\n}\n```\n\n```json\n{\n  \"tool\": \"ssh_close_connection\",\n  \"arguments\": {\n    \"host\": \"kubemaster01.prod.example.com\"\n  }\n}\n```\n\n## Security Features\n\n### Password Encryption\n\nEncrypt passwords before storing them in environment variables. The encryption utility uses AES-256-GCM with a machine-specific key.\n\nUsers should implement their own password encryption utility or use the source code from this repository's `scripts/encrypt-password.ts` as a reference.\n\n### Authentication Methods\n\n- **SSH Key Authentication**: Supports standard SSH keys with optional passphrase\n- **Password Authentication**: Uses encrypted passwords from environment variables\n- **Secure Ciphers**: AES-CTR, SHA2 algorithms for SSH connections\n- **Connection Timeouts**: Prevents hanging connections\n\n### Command Confirmation\n\nLayered confirmation system for safe execution:\n\n1. **Server-Side Approval**: Native dialog blocks execution (when `askUserApproval: true`)\n2. **Tool Annotations**: Tools marked `destructiveHint: true` require client approval\n3. **Dry-Run Preview**: Test commands without execution using `dryRun: true`\n\n## Hostname Patterns\n\nThe server supports dynamic hostname generation following this pattern:\n\n```\n{nodeType}{number}.{pod}.{environment}.{region}.{domain}\n```\n\n**Examples:**\n- `kubemaster01.prod.env.us-east.example.com`\n- `kubenode01.prod.env.us-east.example.com`\n- `ctrl01.prod.env.us-east.example.com`\n\n**Valid Values:**\n- **Environments**: prod, staging, dev\n- **Regions**: us-east, us-west, eu-central\n- **Node Types**: kubemaster, kubenode, ctrl, app, db\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Run tests\nnpm test\n\n# Start development server\nnpm run dev\n\n# Encrypt a password\nnpm run encrypt-password\n```\n\n## Architecture\n\n### File Structure\n\n```\nsrc/\n├── index.ts          # MCP server entry point\n├── config.ts         # App configuration loader\n├── ssh-manager.ts    # SSH connection management & pooling\n├── crypto-utils.ts   # AES-256-GCM password encryption\n├── host-generator.ts # Dynamic hostname generation\n├── host-config.ts    # Host alias configuration\n├── logger.ts         # Structured logging\n├── types.ts          # TypeScript interfaces\n├── confirmation.ts   # Command approval system\n└── tool-schemas.ts   # MCP tool definitions\n\nscripts/\n└── ssh-approval.vbs      # Windows approval dialog\n```\n\n### Key Components\n\n**SSHConnectionManager**\n- Persistent connection pooling\n- Automatic health monitoring\n- Connection reuse for efficiency\n- Graceful cleanup\n\n**HostConfigManager**\n- Load host aliases from `hosts.json`\n- Resolve aliases to connection details\n- Runtime configuration reload\n\n**HostGenerator**\n- Dynamic hostname generation\n- Pattern validation\n- Infrastructure mapping\n\n## Requirements\n\n- Node.js >= 18.0.0\n- SSH access to target servers\n- SSH key or password authentication credentials\n\n## Error Handling\n\nThe server provides detailed error information:\n- Connection failures with diagnostic messages\n- Authentication errors with suggestions\n- Command execution failures with exit codes\n- Invalid parameter validation\n- Network timeout issues\n\n## License\n\nMIT © hbarhate\n","readmeFilename":"README.md","_rev":"1-f7eb4600c62ef87cbf051e4bc1422d5c"}