{"_id":"@iflow-mcp/mcp-ssh-manager","name":"@iflow-mcp/mcp-ssh-manager","dist-tags":{"latest":"3.1.0"},"versions":{"3.1.0":{"name":"@iflow-mcp/mcp-ssh-manager","version":"3.1.0","description":"MCP SSH Manager: Model Context Protocol server for SSH remote server management. Control SSH connections from Claude Code and OpenAI Codex - execute commands, transfer files, database operations, backups, health monitoring, and DevOps automation. NEW: Too","main":"src/index.js","bin":{"mcp-ssh-manager":"src/index.js"},"type":"module","scripts":{"start":"node src/index.js","setup":"npm install && pip install -r tools/requirements.txt","configure":"python tools/server-manager.py","test-connection":"python tools/test-connection.py","test":"npm run test:profiles && npm run test:aliases && npm run test:hooks && npm run test:tools","test:profiles":"node tests/test-profiles.js","test:aliases":"node tests/test-command-aliases.js","test:hooks":"node tests/test-hooks.js","test:tools":"node tests/test-tool-registry.js","test:all":"npm test && ./scripts/validate.sh","validate":"./scripts/validate.sh","lint":"eslint src/*.js","format":"prettier --write 'src/**/*.js' 'tests/**/*.js'"},"keywords":["mcp","ssh","mcp-ssh","mcp ssh","ssh-mcp","ssh mcp","model-context-protocol-ssh","mcp-server","mcp server ssh","claude-code","claude-ssh","claude-code-ssh","openai-codex","codex","model-context-protocol","remote-server","ssh-manager","ssh manager mcp","remote-ssh","ssh-automation","deployment","devops","automation","backup","restore","health-monitoring","database","mysql","postgresql","mongodb","profiles","hooks","aliases","toml","ai-assistant","ai-tools","llm-tools"],"author":{"name":"MCP SSH Manager Contributors"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/bvisible/mcp-ssh-manager.git"},"bugs":{"url":"https://github.com/bvisible/mcp-ssh-manager/issues"},"homepage":"https://github.com/bvisible/mcp-ssh-manager#readme","dependencies":{"@iarna/toml":"^2.2.5","@modelcontextprotocol/sdk":"^1.17.2","dotenv":"^16.4.5","ssh2":"^1.17.0","uuid":"^11.1.0","zod":"^3.25.76"},"devDependencies":{"eslint":"^8.56.0","prettier":"^3.2.4"},"engines":{"node":">=18.0.0"},"_id":"@iflow-mcp/mcp-ssh-manager@3.1.0","gitHead":"a2aaeba492e145471e14840c16a06bfc500723c4","_nodeVersion":"20.8.1","_npmVersion":"10.1.0","dist":{"integrity":"sha512-OmPXBmjRxxKfgqMP/Q5SXzTgQzO1Tubsjdv6GTGgjK89bpkBtJtXD9gpqakS2QYetdDLyEHhMq5H8T2ihgqmfw==","shasum":"e181d28e35fa29533399fb1c368f68bc119849bf","tarball":"https://registry.npmjs.org/@iflow-mcp/mcp-ssh-manager/-/mcp-ssh-manager-3.1.0.tgz","fileCount":60,"unpackedSize":541144,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDy3FCTgQYQCBSeYeOZdc6eFwniw1v92cgvdcRKJkn5nwIhALXacP4W5LZSszPYyyazbRWCCfisIdvqOz41VBVSOXvq"}]},"_npmUser":{"name":"chatflowdev","email":"chatflowdev@gmail.com"},"directories":{},"maintainers":[{"name":"chatflowdev","email":"chatflowdev@gmail.com"},{"name":"qystart","email":"987472953@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-ssh-manager_3.1.0_1764924380945_0.6303479764235762"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-05T08:46:20.821Z","3.1.0":"2025-12-05T08:46:21.147Z","modified":"2025-12-05T08:46:21.505Z"},"maintainers":[{"name":"chatflowdev","email":"chatflowdev@gmail.com"},{"name":"qystart","email":"987472953@qq.com"}],"description":"MCP SSH Manager: Model Context Protocol server for SSH remote server management. Control SSH connections from Claude Code and OpenAI Codex - execute commands, transfer files, database operations, backups, health monitoring, and DevOps automation. NEW: Too","homepage":"https://github.com/bvisible/mcp-ssh-manager#readme","keywords":["mcp","ssh","mcp-ssh","mcp ssh","ssh-mcp","ssh mcp","model-context-protocol-ssh","mcp-server","mcp server ssh","claude-code","claude-ssh","claude-code-ssh","openai-codex","codex","model-context-protocol","remote-server","ssh-manager","ssh manager mcp","remote-ssh","ssh-automation","deployment","devops","automation","backup","restore","health-monitoring","database","mysql","postgresql","mongodb","profiles","hooks","aliases","toml","ai-assistant","ai-tools","llm-tools"],"repository":{"type":"git","url":"git+https://github.com/bvisible/mcp-ssh-manager.git"},"author":{"name":"MCP SSH Manager Contributors"},"bugs":{"url":"https://github.com/bvisible/mcp-ssh-manager/issues"},"license":"MIT","readme":"# MCP SSH Manager - SSH Remote Server Management via Model Context Protocol ๐Ÿš€\n\n> **Looking for MCP SSH tools?** This is the **MCP SSH Manager** - a complete Model Context Protocol (MCP) server for SSH remote server management compatible with Claude Code and OpenAI Codex.\n\nA powerful Model Context Protocol (MCP) server that enables **Claude Code** and **OpenAI Codex** to manage multiple SSH connections seamlessly. Control remote servers, execute commands, transfer files, manage databases, and automate DevOps tasks directly from your AI assistant.\n\n**Keywords:** MCP SSH, MCP SSH Manager, SSH MCP, Model Context Protocol SSH, Claude Code SSH, SSH MCP Server, Remote SSH Management, MCP Server SSH\n\n
\n\n[![npm version](https://img.shields.io/npm/v/mcp-ssh-manager.svg?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/mcp-ssh-manager)\n[![npm downloads](https://img.shields.io/npm/dt/mcp-ssh-manager.svg?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/mcp-ssh-manager)\n[![MCP SSH Server](https://img.shields.io/badge/MCP_SSH-Server-orange?style=for-the-badge)](https://github.com/bvisible/mcp-ssh-manager)\n[![SSH MCP](https://img.shields.io/badge/SSH_MCP-Compatible-blue?style=for-the-badge)](https://modelcontextprotocol.io)\n[![Version](https://img.shields.io/badge/Version-3.1.0-brightgreen?style=for-the-badge)](https://github.com/bvisible/mcp-ssh-manager/releases/tag/v3.1.0)\n[![Claude Code](https://img.shields.io/badge/Claude_Code-Compatible-5A67D8?style=for-the-badge&logo=anthropic)](https://claude.ai/code)\n[![OpenAI Codex](https://img.shields.io/badge/OpenAI_Codex-Compatible-00A67E?style=for-the-badge&logo=openai)](https://openai.com/codex)\n[![MCP](https://img.shields.io/badge/MCP-Server-orange?style=for-the-badge)](https://modelcontextprotocol.io)\n[![License](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](LICENSE)\n\n\n \"SSH\n\n\n
\n\n\n \"MseeP.ai\n\n\n
\n\n---\n\n## ๐ŸŽ‰ What's New in v3.1.0\n\n**Tool Activation System** (Released: November 15, 2025)\n\n### ๐ŸŽฏ Context Usage Optimization\n- **92% context reduction**: Enable only the tools you need (minimal mode: 5 tools vs all 37)\n- **Tool management CLI**: `ssh-manager tools list/configure/enable/disable`\n- **6 tool groups**: Core, Sessions, Monitoring, Backup, Database, Advanced\n- **Auto-approval export**: Generate Claude Code auto-approval configs\n\n---\n\n## Previous Releases\n\n### v3.0.0 - Enterprise DevOps Platform (October 1, 2025)\n\nThis release adds **12 new MCP tools** transforming SSH Manager into a comprehensive DevOps automation platform:\n\n### ๐Ÿ’พ Backup & Restore System (4 tools)\n- **Automated backups** for MySQL, PostgreSQL, MongoDB, and file systems\n- **Smart scheduling** with cron integration and retention policies\n- **One-click restore** with cross-database support\n- **Metadata tracking** for audit and compliance\n\n### ๐Ÿฅ Health & Monitoring (4 tools)\n- **Real-time health checks** with CPU, RAM, Disk, and Network metrics\n- **Service monitoring** for nginx, mysql, docker, and custom services\n- **Process management** with CPU/RAM sorting and kill capabilities\n- **Alert thresholds** with configurable notifications\n\n### ๐Ÿ—„๏ธ Database Management (4 tools)\n- **Safe database dumps** with compression and selective exports\n- **Database imports** with automatic decompression\n- **Schema exploration** listing databases, tables, and collections\n- **Secure queries** with SQL injection prevention (SELECT-only)\n\n**๐Ÿ“Š Total: 37 MCP Tools** | **๐Ÿ”ง ~4,100 Lines of Code Added** | **โœ… Production Ready**\n\n[Read Full Changelog โ†’](CHANGELOG.md#300---2025-10-01)\n\n---\n\n## ๐Ÿ“‘ Table of Contents\n\n- [Features](#-features)\n- [Quick Start - Claude Code](#-quick-start---claude-code)\n- [Quick Start - OpenAI Codex](#-quick-start---openai-codex)\n- [Prerequisites](#-prerequisites)\n- [Available MCP Tools](#-available-mcp-tools)\n- [Configuration](#-configuration)\n- [Usage Examples](#-usage-examples)\n- [Troubleshooting](#-troubleshooting)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n---\n\n## ๐ŸŒŸ Features\n\n### Core Features\n- **๐Ÿ”— Multiple SSH Connections** - Manage unlimited SSH servers from a single interface\n- **๐Ÿ” Secure Authentication** - Support for both password and SSH key authentication\n- **๐Ÿ“ File Operations** - Upload and download files between local and remote systems\n- **โšก Command Execution** - Run commands on remote servers with working directory support\n- **๐Ÿ“‚ Default Directories** - Set default working directories per server for convenience\n- **๐ŸŽฏ Easy Configuration** - Simple `.env` file setup with guided configuration tool\n\n### Enterprise DevOps Features (v3.0) ๐ŸŽ‰\n- **๐Ÿ’พ Backup & Restore** - Automated backups for MySQL, PostgreSQL, MongoDB, and files\n- **๐Ÿฅ Health Monitoring** - Real-time server health checks (CPU, RAM, Disk, Services)\n- **๐Ÿ—„๏ธ Database Management** - Safe database operations with SQL injection prevention\n- **๐Ÿ“Š Process Management** - Monitor and control server processes\n- **โš ๏ธ Smart Alerts** - Configurable health thresholds and notifications\n\n### v2.0 Features\n- **๐Ÿš€ Bash CLI** - Lightning-fast pure Bash CLI for server management\n- **๐Ÿ“Š Advanced Logging** - Comprehensive logging system with levels and history\n- **๐Ÿ”„ Rsync Integration** - Bidirectional file sync with rsync support\n- **๐Ÿ’ป Persistent Sessions** - Maintain shell context across multiple commands\n- **๐Ÿ‘ฅ Server Groups** - Execute commands on multiple servers simultaneously\n- **๐Ÿ”ง SSH Tunnels** - Local/remote port forwarding and SOCKS proxy support\n- **๐Ÿ“ˆ System Monitoring** - Real-time monitoring of CPU, memory, disk, and network\n- **๐Ÿท๏ธ Server Aliases** - Use short aliases instead of full server names\n- **๐Ÿš€ Smart Deployment** - Automated file deployment with permission handling\n- **๐Ÿ”‘ Sudo Support** - Execute commands with sudo privileges securely\n- **๐Ÿ“ OpenAI Codex Support** - Compatible with OpenAI Codex via TOML configuration\n\n---\n\n## โš™๏ธ Tool Management & Context Optimization\n\n**NEW in v3.1**: Reduce Claude Code context usage by 92% with tool activation management!\n\nMCP SSH Manager includes **37 tools** organized into **6 groups**. By default, all tools are enabled, but you can optimize for your specific workflow:\n\n### Quick Setup\n\n```bash\n# Interactive configuration wizard\nssh-manager tools configure\n\n# View current configuration\nssh-manager tools list\n\n# Enable/disable specific groups\nssh-manager tools enable monitoring\nssh-manager tools disable backup\n```\n\n### Configuration Modes\n\n| Mode | Tools | Context Usage | Best For |\n|------|-------|---------------|----------|\n| **All** (default) | 37 tools | ~43.5k tokens | Full feature set, most users |\n| **Minimal** | 5 tools | ~3.5k tokens | Basic SSH operations only |\n| **Custom** | 5-37 tools | Varies | Tailored to your workflow |\n\n### Tool Groups\n\n- **Core** (5 tools) - Always enabled: list, execute, upload, download, sync\n- **Sessions** (4 tools) - Persistent SSH sessions\n- **Monitoring** (6 tools) - Health checks, service status, process management\n- **Backup** (4 tools) - Database and file backups\n- **Database** (4 tools) - MySQL, PostgreSQL, MongoDB operations\n- **Advanced** (14 tools) - Deployment, sudo, tunnels, groups, aliases, etc.\n\n### Benefits\n\n- **92% context reduction** in minimal mode (~40k tokens saved)\n- **Fewer approval prompts** in Claude Code\n- **Faster loading** and cleaner interface\n- **Auto-approval configuration** export for Claude Code\n\n๐Ÿ“– [**Complete Tool Management Guide โ†’**](docs/TOOL_MANAGEMENT.md)\n\n---\n\n## ๐Ÿ” Alternative Search Terms\n\nLooking for:\n- **MCP SSH** server? โœ… You're in the right place\n- **SSH MCP** integration? โœ… This is it\n- **Claude Code SSH** tools? โœ… Fully compatible\n- **Model Context Protocol SSH** manager? โœ… Complete solution\n- **OpenAI Codex SSH** server? โœ… Full support\n- **Remote SSH MCP** server? โœ… Works seamlessly\n- **MCP Server for SSH**? โœ… Production ready\n- **SSH automation with AI**? โœ… Perfect tool\n\nThis is **the** MCP SSH Manager you've been searching for! ๐ŸŽฏ\n\n---\n\n## ๐Ÿ“‹ Prerequisites\n\n- Node.js (v18 or higher)\n- npm (comes with Node.js)\n- **For Claude Code**: Claude Code CLI installed\n- **For OpenAI Codex**: Codex CLI configured\n- Bash 4.0+ (for CLI management tools)\n- rsync (for file synchronization)\n- sshpass (optional, for rsync with password authentication)\n - macOS: `brew install hudochenkov/sshpass/sshpass`\n - Linux: `apt-get install sshpass`\n\n## ๐Ÿš€ Quick Start - Claude Code\n\n### 1. Install MCP SSH Manager\n\n**Option A: Install from npm (recommended)**\n\n```bash\n# Install globally from npm\nnpm install -g mcp-ssh-manager\n\n# Or install locally\nnpx mcp-ssh-manager\n```\n\n**Option B: Install from source**\n\n```bash\n# Clone and install\ngit clone https://github.com/bvisible/mcp-ssh-manager.git\ncd mcp-ssh-manager\nnpm install\n\n# Install the Bash CLI\ncd cli && ./install.sh\n\n# Configure your first server\nssh-manager server add\n```\n\n### 2. Install to Claude Code\n\n```bash\n# For personal use (current user only)\nclaude mcp add ssh-manager node /path/to/mcp-ssh-manager/src/index.js\n\n# For team sharing (creates .mcp.json in project)\nclaude mcp add ssh-manager --scope project node /path/to/mcp-ssh-manager/src/index.js\n\n# For all your projects\nclaude mcp add ssh-manager --scope user node /path/to/mcp-ssh-manager/src/index.js\n```\n\n### 3. Configure Auto-Approval (Optional but Recommended)\n\nTo avoid being prompted for approval on every SSH command, add auto-approve configuration:\n\nEdit `~/.config/claude-code/claude_code_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"ssh-manager\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-ssh-manager/src/index.js\"],\n \"autoApprove\": [\n \"mcp__ssh-manager__ssh_execute\",\n \"mcp__ssh-manager__ssh_list_servers\",\n \"mcp__ssh-manager__ssh_upload\",\n \"mcp__ssh-manager__ssh_download\",\n \"mcp__ssh-manager__ssh_sync\",\n \"mcp__ssh-manager__ssh_alias\"\n ]\n }\n }\n}\n```\n\n**Important**: Restart Claude Code after making this change.\n\nFor full auto-approval of all SSH tools, see the complete list in [examples/claude-code-config.example.json](examples/claude-code-config.example.json).\n\n### 4. Start Using!\n\nIn Claude Code, you can now:\n\n```\n\"List all my SSH servers\"\n\"Execute 'ls -la' on production server\" # Uses default directory if set\n\"Run 'docker ps' on staging\"\n\"Upload config.json to production:/etc/app/config.json\"\n\"Download logs from staging:/var/log/app.log\"\n```\n\n**With Default Directories:**\nIf you set `/var/www/html` as default for production, these commands are equivalent:\n- `\"Run 'ls' on production\"` โ†’ executes in `/var/www/html`\n- `\"Run 'ls' on production in /tmp\"` โ†’ executes in `/tmp` (overrides default)\n\n---\n\n## ๐Ÿš€ Quick Start - OpenAI Codex\n\n### 1. Install MCP SSH Manager\n\nSame installation as Claude Code (see above), then configure for Codex:\n\n```bash\n# Set up Codex integration\nssh-manager codex setup\n\n# Migrate existing servers to TOML format (if you have .env servers)\nssh-manager codex migrate\n\n# Test the integration\nssh-manager codex test\n```\n\n### 2. Manual Configuration (Optional)\n\nIf you prefer manual setup, add to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.ssh-manager]\ncommand = \"node\"\nargs = [\"/absolute/path/to/mcp-ssh-manager/src/index.js\"]\nenv = { SSH_CONFIG_PATH = \"/Users/you/.codex/ssh-config.toml\" }\nstartup_timeout_ms = 20000\n```\n\n### 3. Configure Servers in TOML Format\n\nCreate or edit `~/.codex/ssh-config.toml`:\n\n```toml\n[ssh_servers.production]\nhost = \"prod.example.com\"\nuser = \"admin\"\npassword = \"secure_password\" # or use key_path\nkey_path = \"~/.ssh/id_rsa\" # for SSH key auth (recommended)\nport = 22\ndefault_dir = \"/var/www\"\ndescription = \"Production server\"\n\n[ssh_servers.staging]\nhost = \"staging.example.com\"\nuser = \"deploy\"\nkey_path = \"~/.ssh/staging_key\"\nport = 2222\ndefault_dir = \"/home/deploy/app\"\n```\n\n๐Ÿ’ก **See [examples/codex-ssh-config.example.toml](examples/codex-ssh-config.example.toml) for more complete examples!**\n\n### 4. Start Using in Codex!\n\nIn OpenAI Codex, you can now:\n\n```\n\"List my SSH servers\"\n\"Execute 'docker ps' on production\"\n\"Upload file.txt to staging:/tmp/\"\n\"Monitor CPU usage on all servers\"\n\"Download production:/var/log/app.log to ./logs/\"\n```\n\n### Converting Between Formats\n\nSwitch easily between Claude Code (.env) and Codex (TOML):\n\n```bash\n# Convert .env to TOML (for Codex)\nssh-manager codex convert to-toml\n\n# Convert TOML back to .env (for Claude Code)\nssh-manager codex convert to-env\n```\n\nBoth formats can coexist! The system supports both simultaneously.\n\n---\n\n## ๐Ÿ› ๏ธ Available MCP Tools\n\n### Core Tools\n\n#### `ssh_list_servers`\nLists all configured SSH servers with their details.\n\n#### `ssh_execute`\nExecute commands on remote servers.\n- Parameters: `server` (name), `command`, `cwd` (optional working directory)\n- **Note**: If no `cwd` is provided, uses the server's default directory if configured\n\n#### `ssh_upload`\nUpload files to remote servers.\n- Parameters: `server`, `local_path`, `remote_path`\n\n#### `ssh_download`\nDownload files from remote servers.\n- Parameters: `server`, `remote_path`, `local_path`\n\n### Backup & Restore Tools (v2.1+) ๐Ÿ”„\n\n#### `ssh_backup_create`\nCreate backup of database or files on remote server.\n- Types: MySQL, PostgreSQL, MongoDB, Files\n- Parameters: `server`, `type`, `name`, `database`, `paths`, `retention`\n- Automatic compression and metadata tracking\n- See [Backup Guide](docs/BACKUP_GUIDE.md) for detailed usage\n\n#### `ssh_backup_list`\nList all available backups on remote server.\n- Parameters: `server`, `type` (optional filter)\n- Returns backup details with size, date, and retention info\n\n#### `ssh_backup_restore`\nRestore from a previous backup.\n- Parameters: `server`, `backupId`, `database`, `targetPath`\n- Supports cross-database restoration\n\n#### `ssh_backup_schedule`\nSchedule automatic backups using cron.\n- Parameters: `server`, `schedule` (cron format), `type`, `name`\n- Automatic cleanup based on retention policy\n\n### Health & Monitoring Tools (v2.2+) ๐Ÿฅ\n\n#### `ssh_health_check`\nPerform comprehensive health check on remote server.\n- Checks: CPU, Memory, Disk, Network, Uptime, Load average\n- Returns overall health status (healthy/warning/critical)\n- Optional detailed mode for extended metrics\n\n#### `ssh_service_status`\nCheck status of services (nginx, mysql, docker, etc.).\n- Parameters: `server`, `services` (array)\n- Returns running/stopped status for each service\n- Works with both systemd and sysv init systems\n\n#### `ssh_process_manager`\nList, monitor, or kill processes on remote server.\n- Actions: list (top processes), kill (terminate), info (details)\n- Sort by CPU or memory usage\n- Filter processes by name\n\n#### `ssh_alert_setup`\nConfigure health monitoring alerts and thresholds.\n- Actions: set (configure), get (view), check (test thresholds)\n- Configurable CPU, memory, and disk thresholds\n- Automatic alert triggering when thresholds exceeded\n\n### Database Management Tools (v2.3+) ๐Ÿ—„๏ธ\n\n#### `ssh_db_dump`\nCreate database dump/backup on remote server.\n- Supports: MySQL, PostgreSQL, MongoDB\n- Parameters: `server`, `type`, `database`, `outputFile`, `dbUser`, `dbPassword`, `dbHost`, `dbPort`\n- Optional: `compress` (gzip), `tables` (specific tables only)\n- Returns dump size and location\n\n#### `ssh_db_import`\nImport SQL dump or restore database on remote server.\n- Supports: MySQL, PostgreSQL, MongoDB\n- Parameters: `server`, `type`, `database`, `inputFile`, `dbUser`, `dbPassword`, `dbHost`, `dbPort`\n- Handles compressed (.gz) files automatically\n- Optional: `drop` (drop database before restore for MongoDB)\n\n#### `ssh_db_list`\nList databases or tables on remote server.\n- Parameters: `server`, `type`, `database` (optional), `dbUser`, `dbPassword`, `dbHost`, `dbPort`\n- Without database: lists all databases (filters system DBs)\n- With database: lists all tables/collections\n- Returns structured list with count\n\n#### `ssh_db_query`\nExecute read-only SQL queries on remote database.\n- Parameters: `server`, `type`, `database`, `query`, `dbUser`, `dbPassword`, `dbHost`, `dbPort`\n- **Security**: Only SELECT queries allowed for safety\n- MongoDB: Use `collection` parameter for find queries\n- Returns query results with row count\n\n### Deployment Tools (v1.2+)\n\n#### `ssh_deploy` ๐Ÿš€\nDeploy files with automatic permission and backup handling.\n- Parameters: `server`, `files` (array), `options` (owner, permissions, backup, restart)\n- Automatically handles permission issues and creates backups\n\n#### `ssh_execute_sudo` ๐Ÿ”\nExecute commands with sudo privileges.\n- Parameters: `server`, `command`, `password` (optional), `cwd` (optional)\n- Securely handles sudo password without exposing in logs\n\n### Server Management\n\n#### `ssh_alias` ๐Ÿท๏ธ\nManage server aliases for easier access.\n- Parameters: `action` (add/remove/list), `alias`, `server`\n- Example: Create alias \"prod\" for \"production\" server\n\n#### `ssh_command_alias` ๐Ÿ“\nManage command aliases for frequently used commands.\n- Parameters: `action` (add/remove/list/suggest), `alias`, `command`\n- Aliases loaded from active profile\n- Example: Custom aliases for your project\n\n#### `ssh_hooks` ๐ŸŽฃ\nManage automation hooks for SSH operations.\n- Parameters: `action` (list/enable/disable/status), `hook`\n- Hooks loaded from active profile\n- Example: Project-specific validation and automation\n\n#### `ssh_profile` ๐Ÿ“š\nManage configuration profiles for different project types.\n- Parameters: `action` (list/switch/current), `profile`\n- Available profiles: default, frappe, docker, nodejs\n- Example: Switch between different project configurations\n\n## ๐Ÿ”ง Configuration\n\n### Profiles\n\nSSH Manager uses profiles to configure aliases and hooks for different project types:\n\n1. **Set active profile**: \n - Environment variable: `export SSH_MANAGER_PROFILE=frappe`\n - Configuration file: Create `.ssh-manager-profile` with profile name\n - Default: Uses `default` profile if not specified\n\n2. **Available profiles**:\n - `default` - Basic SSH operations\n - `frappe` - Frappe/ERPNext specific\n - `docker` - Docker container management\n - `nodejs` - Node.js applications\n - Create custom profiles in `profiles/` directory\n\n### Environment Variables\n\nServers are configured in the `.env` file with this pattern:\n\n```env\n# Server configuration pattern\nSSH_SERVER_[NAME]_HOST=hostname_or_ip\nSSH_SERVER_[NAME]_USER=username\nSSH_SERVER_[NAME]_PASSWORD=password # For password auth\nSSH_SERVER_[NAME]_KEYPATH=~/.ssh/key # For SSH key auth\nSSH_SERVER_[NAME]_PORT=22 # Optional, defaults to 22\nSSH_SERVER_[NAME]_DEFAULT_DIR=/path/to/dir # Optional, default working directory\nSSH_SERVER_[NAME]_DESCRIPTION=Description # Optional\n\n# Example\nSSH_SERVER_PRODUCTION_HOST=prod.example.com\nSSH_SERVER_PRODUCTION_USER=admin\nSSH_SERVER_PRODUCTION_PASSWORD=secure_password\nSSH_SERVER_PRODUCTION_PORT=22\nSSH_SERVER_PRODUCTION_DEFAULT_DIR=/var/www/html\nSSH_SERVER_PRODUCTION_DESCRIPTION=Production Server\nSSH_SERVER_PRODUCTION_SUDO_PASSWORD=secure_sudo_pass # Optional, for automated deployments\n```\n\n### Server Management Tool\n\nThe Python management tool (`tools/server_manager.py`) provides:\n\n1. **List servers** - View all configured servers\n2. **Add server** - Interactive server configuration\n3. **Test connection** - Verify server connectivity\n4. **Remove server** - Delete server configuration\n5. **Update Claude Code** - Configure MCP in Claude Code\n6. **Install dependencies** - Setup required packages\n\n## ๐Ÿ“ Project Structure\n\n```\nmcp-ssh-manager/\nโ”œโ”€โ”€ src/\nโ”‚ โ””โ”€โ”€ index.js # Main MCP server implementation\nโ”œโ”€โ”€ tools/\nโ”‚ โ”œโ”€โ”€ server_manager.py # Interactive server management\nโ”‚ โ”œโ”€โ”€ test-connection.py # Connection testing utility\nโ”‚ โ””โ”€โ”€ requirements.txt # Python dependencies\nโ”œโ”€โ”€ examples/\nโ”‚ โ”œโ”€โ”€ .env.example # Example configuration\nโ”‚ โ”œโ”€โ”€ claude-code-config.example.json\nโ”‚ โ”œโ”€โ”€ backup-workflow.js # Backup and restore examples\nโ”‚ โ””โ”€โ”€ codex-ssh-config.example.toml\nโ”œโ”€โ”€ package.json # Node.js dependencies\nโ”œโ”€โ”€ .env # Your server configurations (create from .env.example)\nโ””โ”€โ”€ README.md # This file\n```\n\n## ๐Ÿงช Testing\n\n### Test Server Connection\n\n```bash\npython tools/test-connection.py production\n```\n\n### Verify MCP Installation\n\n```bash\nclaude mcp list\n```\n\n### Check Server Status in Claude Code\n\n```\n/mcp\n```\n\n## ๐Ÿ”’ Security Best Practices\n\n1. **Never commit `.env` files** - Always use `.env.example` as template\n2. **Use SSH keys when possible** - More secure than passwords\n3. **Limit server access** - Use minimal required permissions\n4. **Rotate credentials** - Update passwords and keys regularly\n\n## ๐Ÿ“š Advanced Usage\n\n### Documentation\n- [DEPLOYMENT_GUIDE.md](docs/DEPLOYMENT_GUIDE.md) - Deployment strategies and permission handling\n- [ALIASES_AND_HOOKS.md](docs/ALIASES_AND_HOOKS.md) - Command aliases and automation hooks\n- Real-world examples and best practices\n\n## ๐Ÿ› Troubleshooting\n\n### Claude Code Crashes / Interruptions\n\n**Symptoms:**\n- Claude shows \"Interrupted: What should Claude do instead?\"\n- MCP tools execute but Claude stops working\n- Commands succeed but Claude freezes\n\n**Solution:** v3.1.1 includes automatic fixes:\n- โœ… Output auto-truncated to prevent context overflow\n- โœ… Timeout increased to 2 minutes (default), max 5 minutes\n- โœ… Standardized error responses\n\n**Performance Tuning** (add to `.env`):\n```bash\n# Reduce output size (default: 10000 characters)\nMCP_SSH_MAX_OUTPUT_LENGTH=5000\n\n# Increase timeout for slow commands (default: 120000ms)\nMCP_SSH_DEFAULT_TIMEOUT=180000\n\n# Use compact JSON to save tokens (default: false)\nMCP_SSH_COMPACT_JSON=true\n```\n\n**For large outputs:**\n```bash\n# Instead of: cat huge-log.txt\n# Use: tail -n 100 huge-log.txt\n# Or: grep ERROR huge-log.txt | tail -n 50\n```\n\nSee [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for complete guide.\n\n### MCP Tools Not Available\n\n1. Ensure MCP is installed: `claude mcp list`\n2. Restart Claude Code after installation\n3. Check server logs for errors\n\n### Connection Failed\n\n1. Test connection: `ssh-manager server test [server_name]`\n2. Verify network connectivity\n3. Check firewall rules\n4. Ensure SSH service is running on remote server\n\n### Permission Denied\n\n1. Verify username and password/key\n2. Check SSH key permissions: `chmod 600 ~/.ssh/your_key`\n3. Ensure user has necessary permissions on remote server\n\n## ๐Ÿ› ๏ธ Available MCP Tools\n\nOnce installed in Claude Code, you'll have access to these powerful tools:\n\n### Core Tools\n- `ssh_execute` - Execute commands on remote servers\n- `ssh_upload` - Upload files to remote servers\n- `ssh_download` - Download files from remote servers\n- `ssh_list_servers` - List all configured SSH servers\n\n### Advanced Tools (v2.0)\n- `ssh_sync` - Bidirectional file synchronization with rsync\n- `ssh_tail` - Real-time log monitoring with follow mode\n- `ssh_monitor` - System metrics monitoring (CPU, RAM, disk, network)\n- `ssh_history` - View command execution history\n\n### Session Management\n- `ssh_session_start` - Start persistent SSH session\n- `ssh_session_send` - Send commands to active session\n- `ssh_session_list` - List active sessions\n- `ssh_session_close` - Close specific session\n\n### Server Groups\n- `ssh_execute_group` - Execute commands on server groups\n- `ssh_group_manage` - Manage server groups (create, update, delete)\n\n### SSH Tunnels\n- `ssh_tunnel_create` - Create SSH tunnels (local, remote, SOCKS)\n- `ssh_tunnel_list` - List active tunnels with statistics\n- `ssh_tunnel_close` - Close specific or all tunnels\n\n### Deployment & Security\n- `ssh_deploy` - Smart deployment with permission handling\n- `ssh_execute_sudo` - Execute commands with sudo privileges\n- `ssh_alias` - Manage server aliases\n\n## ๐Ÿ“š Usage Examples\n\n### Backup & Restore\n\n```\n\"Backup production MySQL database before deployment\"\n\"List all backups on production server\"\n\"Restore backup from yesterday\"\n\"Schedule daily database backup at 2 AM\"\n\"Backup website files excluding cache and logs\"\n```\n\nFor detailed backup examples, see [examples/backup-workflow.js](examples/backup-workflow.js) and [docs/BACKUP_GUIDE.md](docs/BACKUP_GUIDE.md).\n\n### Using the Bash CLI\n\n```bash\n# Basic server management\nssh-manager server list\nssh-manager server add\nssh-manager ssh prod1\n\n# File synchronization\nssh-manager sync push prod1 ./app /var/www/\nssh-manager sync pull prod1 /var/log/app.log ./\n\n# SSH tunnels\nssh-manager tunnel create prod1 local 3307:localhost:3306\nssh-manager tunnel list\n\n# Execute commands\nssh-manager exec prod1 \"docker ps\"\n```\n\n### Using in Claude Code or OpenAI Codex\n\nOnce installed, simply ask your AI assistant:\n\n**Claude Code examples:**\n- \"List my SSH servers\"\n- \"Execute 'df -h' on production server\"\n- \"Upload this file to staging:/var/www/\"\n- \"Create an SSH tunnel to access remote MySQL\"\n- \"Monitor CPU usage on all servers\"\n- \"Start a persistent session on prod1\"\n\n**OpenAI Codex examples:**\n- \"Show my SSH servers\"\n- \"Run df -h on production\"\n- \"Upload file.txt to staging:/tmp/\"\n- \"Check CPU usage on all servers\"\n\nBoth AI assistants support the same MCP tools! ๐Ÿš€\n\n---\n\n## ๐Ÿค Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n1. Fork the repository\n2. Clone and install dependencies\n3. **Setup pre-commit hooks** for code quality:\n ```bash\n ./scripts/setup-hooks.sh\n ```\n4. Create your feature branch\n5. Make your changes (hooks will validate on commit)\n6. Push to your branch\n7. Open a Pull Request\n\n### Code Quality\n\nThis project uses automated quality checks:\n- **ESLint** for JavaScript linting\n- **Black** for Python formatting\n- **Flake8** for Python linting\n- **Prettier** for code formatting\n- **Pre-commit hooks** for automated validation\n- **Secret detection** to prevent credential leaks\n\nRun validation manually: `./scripts/validate.sh`\n\n## ๐Ÿ“„ License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## ๐Ÿ™ Acknowledgments\n\n- Built for [Claude Code](https://claude.ai/code)\n- Uses the [Model Context Protocol](https://modelcontextprotocol.io)\n- SSH handling via [node-ssh](https://www.npmjs.com/package/node-ssh)\n- Server management with [Paramiko](https://www.paramiko.org)\n\n## ๐Ÿ“ง Support\n\nFor issues, questions, or suggestions:\n- Open an issue on [GitHub Issues](https://github.com/yourusername/mcp-ssh-manager/issues)\n- Check existing issues before creating new ones\n\n---\n\nMade with โค๏ธ for the Claude Code community\n\n## Known Limitations\n\n### Command Timeout\n- The timeout parameter for SSH commands is advisory only\n- Due to SSH2 library limitations, commands may continue running on the server even after timeout\n- For critical timeout needs, use the system's `timeout` command directly in your command\n\n### SSH Sync (rsync)\n- Password authentication requires `sshpass` to be installed\n- SSH key authentication is recommended for better security and reliability\n- Large file transfers may take time and appear to hang - be patient\n\n### Connection Management\n- Connections are pooled and reused for performance\n- If a connection becomes stale, it will be automatically reconnected on next use\n- Force reconnection by using the `ssh_connection_status` tool with `reconnect` action\n\n## Support\n\nFor issues, feature requests, or contributions, please visit:\nhttps://github.com/bvisible/mcp-ssh-manager\n","readmeFilename":"README.md","_rev":"1-71e28bba1bc711690449cee2c05e6755"}