Content
# SSH MCP Tool
[](https://opensource.org/licenses/ISC)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://github.com/shuakami/mcp-ssh)
[中文版本 (README.md)](README.md)
## What is this
This is an SSH tool based on MCP (Model Context Protocol) that allows AI models to access and manage SSH connections through a standardized interface.
In simple terms, it enables AI assistants to perform various SSH operations, such as connecting to servers, executing commands, and managing files, without the user having to manually input complex commands or switch to a terminal.
<details>
<summary><b>Supported Features</b> (click to expand)</summary>
- **Connection Management**: Create, retrieve, list, update, and delete SSH connections
- **Command Execution**: Execute single commands, compound commands, and background tasks
- **tmux Session Management**: Create, retrieve, list, send keys, and capture output
- **File Operations**: Upload, download, and view file contents
- **Process Management**: Detect blocking processes, smart waiting, and timeout handling
- **Security Control**: Password/key authentication, timeout control, and error handling
</details>
<details>
<summary><b>Feature Highlights</b> (click to expand)</summary>
Here are some core features of the SSH MCP tool:
- **Intelligent Command Execution**: Automatically detects and waits for blocking processes to avoid session freezes
- **tmux Integration**: Fully supports tmux session management for persistent terminal sessions
- **Compound Command Support**: Smartly handles compound commands containing `&&` and `;`
- **Real-time Feedback**: Command execution status is updated in real-time, supporting long-running tasks
- **Error Recovery**: Automatically handles disconnections, reconnections, timeouts, and other exceptional situations
- **Secure and Reliable**: Supports multiple authentication methods to protect sensitive information
With simple natural language instructions, the AI can help you complete all of the above operations without manually writing complex SSH commands or executing operations in the terminal.
</details>
## Quick Start
### 0. Environment Preparation
<details>
<summary>System Requirements (click to expand)</summary>
1. **Python 3.11+ (required)**
- Visit the [Python official website](https://www.python.org/downloads/)
- Download and install Python 3.11 or higher
- **Important**: During installation, make sure to check the "Add Python to PATH" option
- **After installation, please restart your computer** to ensure the environment variables take effect
2. **Node.js and npm**
- Visit the [Node.js official website](https://nodejs.org/)
- Download and install the LTS (Long Term Support) version
- You can choose the default options during installation; the installer will install both Node.js and npm
3. **Git**
- Visit the [Git official website](https://git-scm.com/)
- Download and install Git
- You can use the default options during installation
4. **tmux (required for remote servers)**
- Install tmux on the remote server
- For Ubuntu/Debian: `sudo apt-get install tmux`
- For CentOS/RHEL: `sudo yum install tmux`
</details>
### 1. Clone and Install
```bash
git clone https://github.com/shuakami/mcp-ssh.git
cd mcp-ssh
npm install
npm run build
```
> ⚠️ **Important Note**: Please do not delete the cloned or extracted files after installation, as the plugin needs continuous access to these files!
### 2. Build the Project
```bash
npm run build
```
### 3. Add to Cursor MCP Configuration
Configure MCP according to your operating system by following the steps below:
<details>
<summary><b>Windows Configuration</b> (click to expand)</summary>
1. In Cursor, open or create the MCP configuration file: `C:\\Users\\your_username\\.cursor\\mcp.json`
- Note: Please replace `your_username` with your Windows username.
2. Add or modify the configuration as follows:
```json
{
"mcpServers": {
"ssh-mcp": {
"command": "pythonw",
"args": [
"C:/Users/your_username/mcp-ssh/bridging_ssh_mcp.py"
]
}
}
}
```
> ⚠️ **Please Note**:
> - Replace `your_username` with your Windows username.
> - Ensure the path correctly points to the directory where you cloned or extracted the project.
> - The path should reflect the actual location where you placed the project files.
> - **Do not delete the cloned or extracted folder**, as this will cause MCP to malfunction.
</details>
<details>
<summary><b>macOS Configuration</b> (click to expand)</summary>
1. In Cursor, open or create the MCP configuration file: `/Users/your_username/.cursor/mcp.json`
- Note: Please replace `your_username` with your macOS username.
2. Add or modify the configuration as follows:
```json
{
"mcpServers": {
"ssh-mcp": {
"command": "python3",
"args": [
"/Users/your_username/mcp-ssh/bridging_ssh_mcp.py"
]
}
}
}
```
> ⚠️ **Please Note**:
> - Replace `your_username` with your macOS username.
> - Ensure the path correctly points to the directory where you cloned or extracted the project.
> - The path should reflect the actual location where you placed the project files.
> - **Do not delete the cloned or extracted folder**, as this will cause MCP to malfunction.
</details>
<details>
<summary><b>Linux Configuration</b> (click to expand)</summary>
1. In Cursor, open or create the MCP configuration file: `/home/your_username/.cursor/mcp.json`
- Note: Please replace `your_username` with your Linux username.
2. Add or modify the configuration as follows:
```json
{
"mcpServers": {
"ssh-mcp": {
"command": "python3",
"args": [
"/home/your_username/mcp-ssh/bridging_ssh_mcp.py"
]
}
}
}
```
> ⚠️ **Please Note**:
> - Replace `your_username` with your Linux username.
> - Ensure the path correctly points to the directory where you cloned or extracted the project.
> - The path should reflect the actual location where you placed the project files.
> - **Do not delete the cloned or extracted folder**, as this will cause MCP to malfunction.
</details>
### 4. Start the Service
After the configuration is complete, restart the Cursor editor, and it will automatically start the MCP service. You can then begin using it.
### 5. Configure SSH Connection
<details>
<summary><b>How to Configure SSH Connection</b> (Click to expand)</summary>
1. In the Cursor editor, use the AI assistant to create a new SSH connection:
```
Please help me create a new SSH connection to my server
```
2. The AI assistant will guide you to provide the following information:
- Host address (IP or domain name)
- Port number (default 22)
- Username
- Authentication method (password or key)
- Other optional configurations (timeout, key path, etc.)
3. Once the connection is created, you can test the connection with the following command:
```
Please help me test the SSH connection I just created
```
</details>
## Usage Examples
<details>
<summary><b>Basic Command Execution</b> (click to expand)</summary>
```
Please execute the ls -la command on the server
```
The AI assistant will:
1. Check for existing SSH connections
2. Execute the command and return the results
3. Format the output for better readability
</details>
<details>
<summary><b>tmux Session Management</b> (click to expand)</summary>
```
Please create a new tmux session and run the top command
```
The AI assistant will:
1. Create a new tmux session
2. Execute the top command within the session
3. Return the session ID for future use
</details>
<details>
<summary><b>File Operations</b> (click to expand)</summary>
```
Please help me view the last 100 lines of the /var/log/syslog file
```
The AI assistant will:
1. Check file permissions
2. Use the appropriate command to read the file
3. Format and return the content
</details>
## Advanced Features
### Blocking Detection
The SSH MCP tool has a built-in intelligent blocking detection mechanism:
- Automatically detects interactive programs (such as vim, nano)
- Identifies blocking processes running in the background
- Supports setting a wait timeout (up to 10 minutes)
- Provides a force execution option (using the force parameter)
### Composite Command Handling
Supports executing composite commands that include `&&` and `;`:
- Intelligent splitting and execution of multiple commands
- Maintains the order of command execution
- Provides detailed execution status
- Supports error handling and rollback
### tmux Integration
Complete tmux session management support:
- Create and manage persistent sessions
- Support sending key sequences
- Real-time capture of session output
- Intelligent handling of session states
## Enhanced Prompt Settings
To better utilize the SSH MCP tool for collaboration with remote servers, it is recommended to add the following CursorRules settings in Cursor:
<details>
<summary><b>Recommended CursorRules Settings</b> (click to expand)</summary>
```
For **ssh tasks that require or may require user assistance**, you can create a tmux session, which is a shareable terminal session, and directly **inform the user** of the command they can use to connect to tmux to collaborate with you (do not tell the user within mcp; you should output it). Then proceed with your task.
**You must perform tasks within tmux. You can use tmux send-keys related commands, and mcp will automatically return the results of the currently running command and the previous command.**
You should check the existing tmux windows before making a decision.
**Note: You must patiently wait (using the sleep command) for the current command to finish running; do not / simultaneously / background / continue executing the next task / command.**
You should not create help files or guides/report files unless explicitly requested by the user. Especially when the user is seeking your assistance, you should state it directly.
```
</details>
After adding this setting, the AI assistant will be able to handle SSH tasks more intelligently, particularly in scenarios that require user collaboration, allowing for the creation of shared tmux sessions to make remote operations more efficient and transparent.
## Working Principle
<details>
<summary>Technical Implementation Details (Click to Expand)</summary>
This tool is implemented 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 performs request validation and type checking through **Zod**.
The main technical components include:
- **SSH Client**: Responsible for establishing and maintaining SSH connections, supporting both password and key authentication.
- **tmux Manager**: Handles the creation, management, and interaction of tmux sessions.
- **Command Execution System**: Supports the execution of single commands and compound commands, providing blocking detection.
- **Process Monitoring**: Monitors process status in real-time to prevent session hangs.
- **File Transfer**: Supports upload and download functionalities, handling various file types.
Each 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, allowing AI models to easily understand the command execution results.
</details>
## Contribution Guidelines
We welcome submissions of Issues and Pull Requests! Before submitting, please:
1. Check existing Issues and PRs
2. Follow the project's coding style
3. Add appropriate test cases
4. Update relevant documentation
## License
This project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.
---
If this project helps you, please give it a Star ⭐️ (｡♥‿♥｡)
## Running with Docker (Recommended)
You can also run this tool in a Docker container. This is the recommended way to use it, as it avoids any potential conflicts with your local environment.
1. **Build the Docker image:**
```bash
docker build -t mcp-ssh .
```
2. **Run the Docker container (with data persistence):**
To ensure that your connection configurations and credentials are not lost after the container restarts, we strongly recommend using Docker volumes.
```bash
# (Before the first run) Create a volume to store data
docker volume create mcp-ssh-data
# Run the container and mount the volume to the container's /root/.mcp-ssh directory
# At the same time, we still recommend mounting your local .ssh directory to use existing keys
docker run -it -v mcp-ssh-data:/root/.mcp-ssh -v ~/.ssh:/root/.ssh mcp-ssh
```
On Windows, please use `%USERPROFILE%\.ssh` instead of `~/.ssh`:
```bash
docker run -it -v mcp-ssh-data:/root/.mcp-ssh -v %USERPROFILE%\.ssh:/root/.ssh mcp-ssh
```
MCP Store
