{
  "markdown": "# @nl4ever/sshmcp\n\n[![npm version](https://img.shields.io/npm/v/@nl4ever/sshmcp)](https://www.npmjs.com/package/@nl4ever/sshmcp)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n**[中文文档](./README.zh-CN.md)**\n\n**Let AI manage your remote servers.** A Model Context Protocol (MCP) server that gives AI assistants full SSH access — execute commands, transfer files, manage multiple servers simultaneously, all through natural conversation.\n\n```\nYou:   \"Deploy the latest build to production server\"\nAI:    connects → uploads build → restarts service → verifies status\n```\n\n## Features\n\n- **21 Tools** — Connect, execute, upload, download, write files, and more\n- **Connection Pool** — Operate multiple servers simultaneously, each command tagged with `server_id`\n- **Zero-Token File Transfer** — SFTP path-based transfer, file content never enters AI context\n- **Directory Upload** — Auto tar.gz compress → upload → remote decompress (fast for many small files)\n- **Async Transfer + Progress** — Background transfer for large files with real-time progress tracking\n- **Quick Connect** — Temporary connections without saving config, returns `host:port` as temp ID\n- **SOCKS4/5 Proxy** — Per-connection proxy support\n- **Jump Host** — SSH ProxyJump for bastion/gateway access\n- **Multi-Auth** — Password, private key, ssh-agent, keyboard-interactive (OTP/2FA)\n\n## Quick Start\n\n### Install globally\n\n```bash\nnpm install -g @nl4ever/sshmcp\n```\n\n### Add to Claude Code\n\n```bash\nclaude mcp add sshmcp sshmcp\n```\n\n### Add to Claude Desktop\n\nEdit `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"sshmcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@nl4ever/sshmcp\"]\n    }\n  }\n}\n```\n\n### Add to Cursor\n\nGo to Settings → MCP Servers → Add:\n\n```json\n{\n  \"sshmcp\": {\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"@nl4ever/sshmcp\"]\n  }\n}\n```\n\n## Tools Overview\n\n### Connection Management\n\n| Tool | Description |\n|------|-------------|\n| `list_servers` | List all configured servers and active connections |\n| `get_server` | View server config details |\n| `add_server` | Add/update server config (password, key, agent, OTP) |\n| `update_server` | Modify server config (only pass fields you want to change) |\n| `delete_server` | Remove a server |\n| `rename_server` | Rename a server ID |\n| `connect` | Manually connect (usually not needed, tools auto-connect) |\n| `quick_connect` | Temporary connection, returns `host:port` as ID |\n| `disconnect` | Disconnect specific server or all connections |\n| `test_connection` | Test connectivity without affecting existing connections |\n\n### Command Execution\n\n| Tool | Description |\n|------|-------------|\n| `execute` | Run shell commands on remote server (with configurable timeout) |\n\n### File Operations\n\n| Tool | Description |\n|------|-------------|\n| `read_file` | Read remote file content (with optional line range) |\n| `write_file` | Write text content to remote file |\n| `upload_file` | Upload local file to remote (supports async mode) |\n| `upload_directory` | Upload directory with auto compress → transfer → decompress |\n| `download_file` | Download remote file to local (supports async mode) |\n| `download_directory` | Download directory with remote compress → transfer → local decompress |\n| `transfer_status` | Check progress of async transfers (size/speed/ETA) |\n\n### Proxy Management\n\n| Tool | Description |\n|------|-------------|\n| `list_proxies` | List all SOCKS proxy presets |\n| `add_proxy` | Add SOCKS4/5 proxy preset |\n| `delete_proxy` | Remove a proxy preset |\n\n## Connection Pool: Multi-Server Operations\n\nAll operation tools take a `server_id` parameter. The connection pool auto-manages connections — no manual connect/disconnect needed:\n\n```\nAI: execute(server_id=\"prod\", command=\"nginx -s reload\")         ← auto-connects to prod\nAI: execute(server_id=\"dev\", command=\"tail -f /var/log/app.log\") ← auto-connects to dev, prod stays\nAI: execute(server_id=\"prod\", command=\"curl localhost\")           ← reuses prod connection\n```\n\nFor temporary servers, use `quick_connect` which returns `host:port` as the ID:\n\n```\nAI: quick_connect(host=\"1.2.3.4\", username=\"root\", password=\"***\")\n→ \"Connected: root@1.2.3.4:22, use server_id=\"1.2.3.4:22\"\"\n\nAI: execute(server_id=\"1.2.3.4:22\", command=\"df -h\")\nAI: disconnect(server_id=\"1.2.3.4:22\")\n```\n\n## Async Transfer (Large Files)\n\nFor large files, enable background transfer mode to avoid blocking:\n\n```\nAI: upload_file(server_id=\"prod\", local_path=\"big.tar.gz\", remote_path=\"/data/\", async_transfer=true)\n→ \"Background upload started: tf_1\"\n\nAI: transfer_status(\"tf_1\")\n→ \"🔄 Uploading: 638.2 MB / 1.2 GB (53.2%) — 12.4 MB/s, ETA 46s\"\n\nAI: transfer_status(\"tf_1\")\n→ \"✅ Upload complete: 1.2 GB, 98s, 12.3 MB/s\"\n```\n\nSmall files use synchronous mode by default — no config needed.\n\n## Connection Examples\n\n### Password authentication\n\n```\nAI: add_server(server_id=\"prod\", name=\"Production\", host=\"10.0.0.1\", username=\"deploy\", password=\"***\")\nAI: execute(server_id=\"prod\", command=\"systemctl status nginx\")\n```\n\n### Private key authentication\n\n```\nAI: add_server(server_id=\"aws\", name=\"AWS EC2\", host=\"ec2-xx.compute.amazonaws.com\", username=\"ubuntu\", private_key=\"~/.ssh/id_rsa\")\n```\n\n### Quick connect (no config saved)\n\n```\nAI: quick_connect(host=\"192.168.1.100\", username=\"root\", password=\"***\")\n→ server_id=\"192.168.1.100:22\"\n\nAI: execute(server_id=\"192.168.1.100:22\", command=\"df -h\")\nAI: disconnect(server_id=\"192.168.1.100:22\")\n```\n\n### Via SOCKS5 proxy\n\n```\nAI: add_proxy(proxy_id=\"tunnel\", name=\"SSH Tunnel\", host=\"127.0.0.1\", port=1080, type=\"5\")\nAI: add_server(server_id=\"internal\", ..., proxy=\"tunnel\")\n```\n\n### Via jump host\n\n```\nAI: add_server(server_id=\"bastion\", name=\"Bastion\", host=\"bastion.example.com\", username=\"admin\", private_key=\"~/.ssh/id_rsa\")\nAI: add_server(server_id=\"internal\", name=\"Internal DB\", host=\"10.0.0.5\", username=\"dbadmin\", password=\"***\", jump_host=\"bastion\")\n```\n\n## Config Location\n\nServer and proxy configurations are stored in:\n\n```\n~/.ssh-mcp/config.json\n```\n\nPasswords are stored in plaintext. For production use, prefer private key authentication.\n\n## Requirements\n\n- Node.js >= 18\n- An MCP-compatible client (Claude Code, Claude Desktop, Cursor, etc.)\n- Remote server with SSH access\n\n## License\n\nMIT\n",
  "bytes": 6393,
  "sha": "a8b732a6e1cf969dfcebb83dfd118d67b9ae14f43e50aaf025c7af1d5d495735",
  "repo_slug": "nikolanddtesla/ssh-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nikolanddtesla_sshmcp_d804e74e/readme"
}