{"id":26718564,"url":"https://github.com/shuakami/mcp-ssh","last_synced_at":"2026-04-17T00:34:13.741Z","repository":{"id":284577773,"uuid":"953377335","full_name":"shuakami/mcp-ssh","owner":"shuakami","description":"🔐 SSH MCP Tool - AI-powered SSH management through MCP protocol | 基于MCP协议的SSH工具，为AI提供SSH远程操作能力","archived":false,"fork":false,"pushed_at":"2025-07-18T03:44:34.000Z","size":113,"stargazers_count":15,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-18T07:28:30.619Z","etag":null,"topics":["ai","ai-tools","automation","cursor","devops","mcp","model-context-protocol","nodejs","remote-management","ssh","terminal","tmux","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shuakami.png","metadata":{"files":{"readme":"README-EN.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-23T08:07:40.000Z","updated_at":"2025-07-18T03:44:38.000Z","dependencies_parsed_at":"2025-07-18T05:51:19.535Z","dependency_job_id":"b3fbd31b-4bb8-4e61-937f-2ec30c9a9c33","html_url":"https://github.com/shuakami/mcp-ssh","commit_stats":null,"previous_names":["shuakami/mcp-ssh"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/shuakami/mcp-ssh","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuakami%2Fmcp-ssh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuakami%2Fmcp-ssh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuakami%2Fmcp-ssh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuakami%2Fmcp-ssh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shuakami","download_url":"https://codeload.github.com/shuakami/mcp-ssh/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuakami%2Fmcp-ssh/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31910165,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"ssl_error","status_checked_at":"2026-04-16T18:21:47.142Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-tools","automation","cursor","devops","mcp","model-context-protocol","nodejs","remote-management","ssh","terminal","tmux","typescript"],"created_at":"2025-03-27T17:35:06.901Z","updated_at":"2026-04-17T00:34:13.725Z","avatar_url":"https://github.com/shuakami.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SSH MCP Tool\n\n[![ISC License](https://img.shields.io/badge/License-ISC-718096?style=flat-square)](https://opensource.org/licenses/ISC)\n[![Node.js](https://img.shields.io/badge/Node.js-18.x-339933?style=flat-square)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6?style=flat-square)](https://www.typescriptlang.org/)\n[![SSH](https://img.shields.io/badge/SSH-MCP-0078d7?style=flat-square)](https://github.com/shuakami/mcp-ssh)\n\n[中文版本 (README.md)](README.md)\n\n## What is this?\n\nThis is an SSH tool based on MCP (Model Context Protocol) that allows AI models to access and manage SSH connections through a standardized interface.\n\nIn simple terms, it enables AI assistants to perform various SSH operations, such as connecting to servers, executing commands, and managing files, without requiring users to manually input complex commands or switch to a terminal.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSupported Features\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n- **Connection Management**: Create, get, list, update, and delete SSH connections\n- **Command Execution**: Execute single commands, compound commands, and background tasks\n- **tmux Session Management**: Create, get, list, send keys, and capture output\n- **File Operations**: Upload, download, and view file contents\n- **Process Management**: Detect blocking processes, smart waiting, and timeout handling\n- **Security Control**: Password/key authentication, timeout control, and error handling\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eKey Features\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\nHere are some core features of the SSH MCP tool:\n\n- **Smart Command Execution**: Automatically detects and waits for blocking processes to prevent session freezes\n- **tmux Integration**: Full support for tmux session management, enabling persistent terminal sessions\n- **Compound Command Support**: Intelligent handling of commands containing `\u0026\u0026` and `;`\n- **Real-time Feedback**: Command execution status updates in real-time, supporting long-running tasks\n- **Error Recovery**: Automatic handling of disconnections, timeouts, and other exceptions\n- **Secure and Reliable**: Supports multiple authentication methods and protects sensitive information\n\nThrough simple natural language instructions, AI can help you complete all of the above operations without manually writing complex SSH commands or operating in the terminal.\n\u003c/details\u003e\n\n## Quick Start\n\n### 0. Environment Setup\n\n\u003cdetails\u003e\n\u003csummary\u003eRequirements (click to expand)\u003c/summary\u003e\n\n1. **Python 3.11+ (Required)**\n   - Visit [Python's website](https://www.python.org/downloads/)\n   - Download and install Python 3.11 or higher\n   - **Important**: Check \"Add Python to PATH\" during installation\n   - **Restart your computer** after installation to ensure environment variables take effect\n\n2. **Node.js and npm**\n   - Visit [Node.js website](https://nodejs.org/)\n   - Download and install the LTS (Long Term Support) version\n   - Use default options during installation, which will install both Node.js and npm\n\n3. **Git**\n   - Visit [Git's website](https://git-scm.com/)\n   - Download and install Git\n   - Use default options during installation\n   \n4. **tmux** (Required on remote servers)\n   - Install tmux on your remote server\n   - For Ubuntu/Debian: `sudo apt-get install tmux`\n   - For CentOS/RHEL: `sudo yum install tmux`\n\u003c/details\u003e\n\n### 1. Clone and Install\n\n```bash\ngit clone https://github.com/shuakami/mcp-ssh.git\ncd mcp-ssh\nnpm install\nnpm run build\n```\n\u003e ⚠️ **Important Note**: Do not delete the cloned or extracted files after installation, as the plugin needs continuous access to these files!\n\n### 2. Build the Project\n\n```bash\nnpm run build\n```\n\n### 3. Add to Cursor MCP Configuration\n\nFollow these steps to configure MCP based on your operating system:\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWindows Configuration\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n1. In Cursor, open or create the MCP configuration file: `C:\\\\Users\\\\YourUsername\\\\.cursor\\\\mcp.json`\n   - Note: Replace `YourUsername` with your Windows username\n\n2. Add or modify the configuration as follows:\n\n```json\n{\n  \"mcpServers\": {\n    \"ssh-mcp\": {\n      \"command\": \"pythonw\",\n      \"args\": [\n        \"C:/Users/YourUsername/mcp-ssh/bridging_ssh_mcp.py\"\n      ]\n    }\n  }\n}\n```\n\n\u003e ⚠️ **Please note**:\n\u003e - Replace `YourUsername` with your Windows username\n\u003e - Make sure the path correctly points to your cloned or extracted project directory\n\u003e - The path should reflect where you actually placed the project files\n\u003e - **Do not delete the cloned or extracted folder**, as this will cause MCP to stop working\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003emacOS Configuration\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n1. In Cursor, open or create the MCP configuration file: `/Users/YourUsername/.cursor/mcp.json`\n   - Note: Replace `YourUsername` with your macOS username\n\n2. Add or modify the configuration as follows:\n\n```json\n{\n  \"mcpServers\": {\n    \"ssh-mcp\": {\n      \"command\": \"python3\",\n      \"args\": [\n        \"/Users/YourUsername/mcp-ssh/bridging_ssh_mcp.py\"\n      ]\n    }\n  }\n}\n```\n\n\u003e ⚠️ **Please note**:\n\u003e - Replace `YourUsername` with your macOS username\n\u003e - Make sure the path correctly points to your cloned or extracted project directory\n\u003e - The path should reflect where you actually placed the project files\n\u003e - **Do not delete the cloned or extracted folder**, as this will cause MCP to stop working\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eLinux Configuration\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n1. In Cursor, open or create the MCP configuration file: `/home/YourUsername/.cursor/mcp.json`\n   - Note: Replace `YourUsername` with your Linux username\n\n2. Add or modify the configuration as follows:\n\n```json\n{\n  \"mcpServers\": {\n    \"ssh-mcp\": {\n      \"command\": \"python3\",\n      \"args\": [\n        \"/home/YourUsername/mcp-ssh/bridging_ssh_mcp.py\"\n      ]\n    }\n  }\n}\n```\n\n\u003e ⚠️ **Please note**:\n\u003e - Replace `YourUsername` with your Linux username\n\u003e - Make sure the path correctly points to your cloned or extracted project directory\n\u003e - The path should reflect where you actually placed the project files\n\u003e - **Do not delete the cloned or extracted folder**, as this will cause MCP to stop working\n\u003c/details\u003e\n\n### 4. Start the Service\n\nAfter configuration, restart the Cursor editor, and it will automatically start the MCP service. You can then begin using it.\n\n### 5. Configure SSH Connection\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eHow to Configure SSH Connection\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n1. In the Cursor editor, use the AI assistant to create a new SSH connection:\n   ```\n   Please help me create a new SSH connection to my server\n   ```\n\n2. The AI assistant will guide you to provide the following information:\n   - Host address (IP or domain name)\n   - Port number (default 22)\n   - Username\n   - Authentication method (password or key)\n   - Other optional configurations (timeout, key path, etc.)\n\n3. After the connection is created, you can test it with:\n   ```\n   Please help me test the SSH connection we just created\n   ```\n\u003c/details\u003e\n\n## Usage Examples\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eBasic Command Execution\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n```\nPlease execute the ls -la command on the server\n```\n\nThe AI assistant will:\n1. Check existing SSH connections\n2. Execute the command and return results\n3. Format output for better readability\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003etmux Session Management\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n```\nPlease create a new tmux session and run the top command\n```\n\nThe AI assistant will:\n1. Create a new tmux session\n2. Execute the top command in the session\n3. Return the session ID for future use\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eFile Operations\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n```\nPlease help me view the last 100 lines of /var/log/syslog\n```\n\nThe AI assistant will:\n1. Check file permissions\n2. Use appropriate commands to read the file\n3. Format and return the content\n\u003c/details\u003e\n\n## Advanced Features\n\n### Blocking Detection\n\nSSH MCP tool includes intelligent blocking detection mechanisms:\n\n- Automatic detection of interactive programs (like vim, nano)\n- Identification of blocking background processes\n- Configurable wait timeout (up to 10 minutes)\n- Force execution option (using the force parameter)\n\n### Compound Command Processing\n\nSupport for executing commands containing `\u0026\u0026` and `;`:\n\n- Smart splitting and execution of multiple commands\n- Maintains command execution order\n- Provides detailed execution status\n- Supports error handling and rollback\n\n### tmux Integration\n\nComplete tmux session management support:\n\n- Create and manage persistent sessions\n- Support for sending keystrokes\n- Real-time session output capture\n- Intelligent session state handling\n\n## Enhanced Prompt Settings\n\nTo better use the SSH MCP tool for remote server collaboration, we recommend adding the following CursorRules setting to Cursor:\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eRecommended CursorRules Setting\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n```\nWhen handling SSH tasks that **need or might need user assistance**, create a tmux session (a shareable terminal session) and **directly tell the user** what command they can use to connect to the tmux session to collaborate with you (output this directly, not within MCP). Then begin your task.\n\n**You must perform tasks within tmux. You can use tmux send-keys related commands, and MCP will automatically return the currently running command and the result of the previous command.**\n\nYou should check existing tmux windows before making a decision.\n\n**Note: When running commands, you must patiently wait (using sleep commands) for the current command to complete, and not run the next task/command simultaneously/in the background/continuing.**\n\nUnless explicitly requested by the user, you should not create help files, guides, or report files. Especially when the user is asking for your help, you should directly say what you need.\n```\n\n\u003c/details\u003e\n\nWith this setting, the AI assistant will be able to handle SSH tasks more intelligently, especially in scenarios requiring user collaboration, by creating shared tmux sessions for more efficient and transparent remote operations.\n\n## How It Works\n\n\u003cdetails\u003e\n\u003csummary\u003eTechnical Implementation Details (click to expand)\u003c/summary\u003e\n\nThis tool is based on the **MCP (Model Context Protocol)** standard, serving as a bridge between AI models and SSH services. It uses **node-ssh** as the underlying SSH client and **Zod** for request validation and type checking.\n\nMain technical components include:\n- **SSH Client**: Responsible for establishing and maintaining SSH connections, supporting password and key authentication\n- **tmux Manager**: Handles the creation, management, and interaction with tmux sessions\n- **Command Execution System**: Supports execution of single commands, compound commands, and provides blocking detection\n- **Process Monitoring**: Real-time detection of process states to prevent session deadlocks\n- **File Transfer**: Supports upload and download functionality, handling various file types\n\nEach SSH operation is encapsulated as a standardized MCP tool, receiving structured parameters and returning formatted results. All remote commands are processed to ensure they are presented in a human-readable format, making it easy for AI models to understand command execution results.\n\u003c/details\u003e\n\n## Contributing\n\nIssues and Pull Requests are welcome! Before submitting, please:\n\n1. Check existing Issues and PRs\n2. Follow the project's code style\n3. Add appropriate test cases\n4. Update relevant documentation\n\n## License\n\nThis project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details\n\n---\n\nIf this project helps you, please give it a Star ⭐️ (｡♥‿♥｡) \n\n## Running with Docker (Recommended)\n\nYou can also run this tool inside a Docker container. This is the recommended way to use it, as it avoids any potential conflicts with your local environment.\n\n1.  **Build the Docker image:**\n\n    ```bash\n    docker build -t mcp-ssh .\n    ```\n\n2.  **Run the Docker container (with data persistence):**\n\n    To ensure your connection configurations and credentials are not lost when the container restarts, we strongly recommend using a Docker Volume.\n\n    ```bash\n    # (Before the first run) Create a volume to store the data\n    docker volume create mcp-ssh-data\n\n    # Run the container and mount the volume to the /root/.mcp-ssh directory inside the container\n    # We also still recommend mounting your local .ssh directory to use your existing keys\n    docker run -it -v mcp-ssh-data:/root/.mcp-ssh -v ~/.ssh:/root/.ssh mcp-ssh\n    ```\n\n    On Windows, you should use `%USERPROFILE%\\.ssh` instead of `~/.ssh`:\n\n    ```bash\n    docker run -it -v mcp-ssh-data:/root/.mcp-ssh -v %USERPROFILE%\\.ssh:/root/.ssh mcp-ssh\n    ``` ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshuakami%2Fmcp-ssh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshuakami%2Fmcp-ssh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshuakami%2Fmcp-ssh/lists"}