Content
# SSH MCP Tool
[](https://opensource.org/licenses/ISC)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://github.com/shuakami/mcp-ssh)
[English Version (README-EN.md)](README-EN.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 allows AI assistants to perform various SSH operations, such as connecting to servers, executing commands, and managing files, without the user having to manually enter complex commands or switch to a terminal.
<details>
<summary><b>Supported Features</b> (Click to expand)</summary>
- **Connection Management**: Create, get, list, update, delete SSH connections
- **Command Execution**: Execute single commands, compound commands, background tasks
- **tmux Session Management**: Create, get, list, send keys, capture output
- **File Operations**: Upload, download, view file content
- **Process Management**: Detect blocking processes, intelligent waiting, timeout handling
- **Security Control**: Password/key authentication, timeout control, error handling
</details>
<details>
<summary><b>Features</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**: Full support for tmux session management, enabling persistent terminal sessions
- **Compound Command Support**: Intelligently handles compound commands containing `&&` and `;`
- **Real-time Feedback**: Real-time updates on command execution status, supporting long-running tasks
- **Error Recovery**: Automatically handles disconnection, reconnection, timeouts, and other exceptions
- **Secure and Reliable**: Supports multiple authentication methods to protect sensitive information
With simple natural language instructions, AI can help you complete all the above operations without manually writing complex SSH commands or executing operations in the terminal.
</details>
## Quick Start
### 0. Environment Preparation
<details>
<summary>Environment Requirements (Click to expand)</summary>
1. **Python 3.11+ (Required)**
- Visit [Python Official Website](https://www.python.org/downloads/)
- Download and install Python 3.11 or later
- **Important**: Check the "Add Python to PATH" option during installation
- **Restart your computer after installation** to ensure the environment variables take effect
2. **Node.js and npm**
- Visit [Node.js Official Website](https://nodejs.org/)
- Download and install the LTS (Long Term Support) version
- Select the default options during installation; the installation package will install both Node.js and npm
3. **Git**
- Visit [Git Official Website](https://git-scm.com/)
- Download and install Git
- 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**: Do not delete the cloned or unzipped files after installation, as the plugin needs to continuously access these files!
### 2. Build Project
```bash
npm run build
```
### 3. Add to Cursor MCP Configuration
Depending on your operating system, follow these steps to configure MCP:
<details>
<summary><b>Windows Configuration</b> (Click to expand)</summary>
1. In Cursor, open or create the MCP configuration file: `C:\\Users\\YourUsername\\.cursor\\mcp.json`
- Note: Replace `YourUsername` with your Windows username
2. Add or modify the configuration as follows:
```json
{
"mcpServers": {
"ssh-mcp": {
"command": "pythonw",
"args": [
"C:/Users/YourUsername/mcp-ssh/bridging_ssh_mcp.py"
]
}
}
}
```
> ⚠️ **Please Note**:
>
> - Replace `YourUsername` with your Windows username
> - Ensure the path correctly points to your cloned or unzipped project directory
> - The path should reflect the actual location where you placed the project files
> - **Do not delete the cloned or unzipped folder**, as this will prevent MCP from working properly
</details>
<details>
<summary><b>macOS Configuration</b> (Click to expand)</summary>
1. In Cursor, open or create the MCP configuration file: `/Users/YourUsername/.cursor/mcp.json`
- Note: Replace `YourUsername` with your macOS username
2. Add or modify the configuration as follows:
```json
{
"mcpServers": {
"ssh-mcp": {
"command": "python3",
"args": [
"/Users/YourUsername/mcp-ssh/bridging_ssh_mcp.py"
]
}
}
}
```
> ⚠️ **Please Note**:
>
> - Replace `YourUsername` with your macOS username
> - Ensure the path correctly points to your cloned or unzipped project directory
> - The path should reflect the actual location where you placed the project files
> - **Do not delete the cloned or unzipped folder**, as this will prevent MCP from working properly
</details>
<details>
<summary><b>Linux Configuration</b> (Click to expand)</summary>
1. In Cursor, open or create the MCP configuration file: `/home/YourUsername/.cursor/mcp.json`
- Note: Replace `YourUsername` with your Linux username
2. Add or modify the configuration as follows:
```json
{
"mcpServers": {
"ssh-mcp": {
"command": "python3",
"args": [
"/home/YourUsername/mcp-ssh/bridging_ssh_mcp.py"
]
}
}
}
```
> ⚠️ **Please Note**:
>
> - Replace `YourUsername` with your Linux username
> - Ensure the path correctly points to your cloned or unzipped project directory
> - The path should reflect the actual location where you placed the project files
> - **Do not delete the cloned or unzipped folder**, as this will prevent MCP from working properly
</details>
### 4. Start Service
After configuring, restart the Cursor editor, and it will automatically start the MCP service. Then you can start 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. After 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 existing SSH connections
2. Execute the command and return the result
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 in 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 waiting timeout (up to 10 minutes)
- Provides a force execution option (using the force parameter)
### Compound Command Handling
Supports executing compound commands containing `&&` and `;`:
- Intelligently splits and executes multiple commands
- Maintains the command execution order
- Provides detailed execution status
- Supports error handling and rollback
### tmux Integration
Complete tmux session management support:
- Create and manage persistent sessions
- Supports sending key sequences
- Real-time capture of session output
- Intelligently handles session status
## Enhanced Prompt Settings
To better use the SSH MCP tool to collaborate 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>
```
When an ssh task **requires or may require user assistance**, create a tmux, a shareable terminal session, and **tell the user directly** what command they can use to connect to tmux to collaborate with you (do not tell the user within mcp, you should output it). Then start 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 running command.**
You should check existing tmux windows before making a decision.
**Note: You must patiently wait (sleep command) for the current command to run, do not/simultaneously/background/continue to execute the next task/command.**
You should not create help files or guide/report files unless the user explicitly requests it. Especially when the user is asking you for help, you should say it directly.
```
</details>
After adding this setting, the AI assistant will be able to handle SSH tasks more intelligently, especially in scenarios that require user collaboration, it can create shared tmux sessions, making remote operations more efficient and transparent.
## How it Works
<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 **Zod** for request validation and type checking.
The main technical components include:
- **SSH Client**: Responsible for establishing and maintaining SSH connections, supporting password and key authentication
- **tmux Manager**: Handles the creation, management, and interaction of tmux sessions
- **Command Execution System**: Supports the execution of single and compound commands and provides blocking detection
- **Process Monitoring**: Real-time detection of process status to avoid session freezes
- **File Transfer**: Supports upload and download functions, 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 Guide
Welcome to submit Issues and Pull Requests! Before submitting, please:
1. Check existing Issues and PRs
2. Follow the project's code 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 highly recommend using Docker data volumes.
```bash
# (First run) Create a data volume to store data
docker volume create mcp-ssh-data
# Run the container and mount the data 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, use `%USERPROFILE%\.ssh` instead of `~/.ssh`:
```bash
docker run -it -v mcp-ssh-data:/root/.mcp-ssh -v %USERPROFILE%\.ssh:/root/.ssh mcp-ssh
```
