Ssh

🚀 SSH MCP Server

This project provides a locally running MCP (Model Context Protocol) service, enabling secure remote control of servers via SSH. It supports command execution and file transfer (SFTP).

✨ Features

• Secure Connection: Supports both password and private key authentication methods.
• Command Execution: Executes commands on the remote server and retrieves the output.
• File Transfer: Supports SFTP for uploading, downloading, reading, and writing files.
• Directory Operations: Lists directories, creates directories, deletes files/directories, and renames files/directories.
• Automatic Connection: Supports pre - configuring the server through environment variables and automatically connects at startup.
• Session Management: Supports concurrent multi - sessions, allowing listing and disconnecting of sessions.
• Timeout Control: Both connection and command execution support timeout settings.

📦 Installation

# Clone the project
git clone https://github.com/lilyjem/ssh.git
cd ssh

# Install dependencies
npm install

# Build the project
npm run build

Configuration Methods

Configuration in Cursor

Find the MCP configuration in Cursor settings (~/.cursor/mcp.json or through the settings interface) and add the following configuration:

Method 1: Pre - configure the server (Recommended)

Pre - configure the server information through environment variables and automatically connect at startup:

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/ssh/dist/index.js"],
      "env": {
        "SSH_HOST": "your-server-ip",
        "SSH_PORT": "22",
        "SSH_USERNAME": "root",
        "SSH_PASSWORD": "your-password"
      }
    }
  }
}

Use private key authentication (more secure):

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/ssh/dist/index.js"],
      "env": {
        "SSH_HOST": "your-server-ip",
        "SSH_PORT": "22",
        "SSH_USERNAME": "root",
        "SSH_PRIVATE_KEY_PATH": "~/.ssh/id_rsa",
        "SSH_PASSPHRASE": "optional-passphrase"
      }
    }
  }
}

Method 2: Manual connection

Do not configure environment variables and manually connect using the ssh_connect tool:

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/ssh/dist/index.js"]
    }
  }
}

Configuration in Claude Desktop

Edit the Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/ssh/dist/index.js"],
      "env": {
        "SSH_HOST": "your-server-ip",
        "SSH_USERNAME": "root",
        "SSH_PASSWORD": "your-password"
      }
    }
  }
}

Configuration in Claude Code (VS Code Extension)

Create a .mcp.json file in the project root directory:

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/ssh/dist/index.js"],
      "env": {
        "SSH_HOST": "your-server-ip",
        "SSH_USERNAME": "root",
        "SSH_PRIVATE_KEY_PATH": "~/.ssh/id_rsa"
      }
    }
  }
}

Or configure the global MCP server in VS Code settings.

Configuration in Codex CLI

Edit the Codex configuration file ~/.codex/config.json:

{
  "mcpServers": {
    "ssh": {
      "command": "node",
      "args": ["/path/to/ssh/dist/index.js"],
      "env": {
        "SSH_HOST": "your-server-ip",
        "SSH_USERNAME": "root",
        "SSH_PASSWORD": "your-password"
      }
    }
  }
}

Run with npx (No need to clone)

If the project is published to npm, you can directly use npx:

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["ssh"],
      "env": {
        "SSH_HOST": "your-server-ip",
        "SSH_USERNAME": "root",
        "SSH_PASSWORD": "your-password"
      }
    }
  }
}

Path Explanation

The /path/to/ssh/dist/index.js in the configuration needs to be replaced with the actual path:

• Windows: C:/Users/yourname/projects/ssh/dist/index.js
• macOS/Linux: /home/yourname/projects/ssh/dist/index.js

Tip: Windows paths can use forward slashes / or double backslashes \\

Environment Variables

*Note: At least one of password, private key content, and private key path must be provided.

Tool List

SSH Connection Management

ssh_connect

Create a new SSH connection (optional when pre - configuring the server).

Parameters:

• host (string, required): Server address
• port (number, optional): SSH port, default is 22
• username (string, required): Username
• password (string, optional): Password
• privateKey (string, optional): Private key content
• passphrase (string, optional): Private key passphrase

ssh_exec

Execute a remote command. No need to provide session_id when pre - configuring the server.

Parameters:

• session_id (string, optional): Session ID
• command (string, required): Command to execute
• timeout (number, optional): Timeout in milliseconds

Example: ssh_exec(command="ls -la /var/log")

ssh_list_sessions

List all active SSH sessions.

ssh_disconnect

Disconnect an SSH connection.

Parameters:

• session_id (string, required): Session ID to disconnect

SFTP File Operations

sftp_list

List the contents of a remote directory.

Parameters:

• session_id (string, optional): Session ID
• path (string, optional): Directory path, default is /

Example: sftp_list(path="/home/user")

sftp_upload

Upload a local file to the remote server.

Parameters:

• session_id (string, optional): Session ID
• local_path (string, required): Local file path
• remote_path (string, required): Remote target path

Example: sftp_upload(local_path="/local/file.txt", remote_path="/home/user/file.txt")

sftp_download

Download a file from the remote server to the local machine.

Parameters:

• session_id (string, optional): Session ID
• remote_path (string, required): Remote file path
• local_path (string, required): Local target path

Example: sftp_download(remote_path="/var/log/syslog", local_path="/local/logs/syslog.txt")

sftp_read

Read the content of a remote file (for text files).

Parameters:

• session_id (string, optional): Session ID
• path (string, required): Remote file path
• encoding (string, optional): Encoding, default is utf - 8

Example: sftp_read(path="/etc/nginx/nginx.conf")

sftp_write

Write content to a remote file.

Parameters:

• session_id (string, optional): Session ID
• path (string, required): Remote file path
• content (string, required): Content to write

Example: sftp_write(path="/home/user/test.txt", content="Hello World")

sftp_delete

Delete a remote file or empty directory.

Parameters:

• session_id (string, optional): Session ID
• path (string, required): Path to delete

Example: sftp_delete(path="/home/user/old-file.txt")

sftp_mkdir

Create a remote directory.

Parameters:

• session_id (string, optional): Session ID
• path (string, required): Directory path

Example: sftp_mkdir(path="/home/user/new-folder")

sftp_rename

Rename or move a remote file/directory.

Parameters:

• session_id (string, optional): Session ID
• old_path (string, required): Original path
• new_path (string, required): New path

Example: sftp_rename(old_path="/home/user/old.txt", new_path="/home/user/new.txt")

💻 Usage Examples

Pre - configured Server Mode

After configuring the environment variables, the service will automatically connect at startup and can be used directly:

User: View the /var/log directory on the server
AI: Call sftp_list(path="/var/log")

User: View the nginx configuration
AI: Call sftp_read(path="/etc/nginx/nginx.conf")

User: Restart the nginx service
AI: Call ssh_exec(command="systemctl restart nginx")

User: Upload the local configuration file to the server
AI: Call sftp_upload(local_path="/local/config/app.conf", remote_path="/etc/app/app.conf")

Manual Connection Mode

User: Connect to my server 192.168.1.100
AI: Call ssh_connect(host="192.168.1.100", username="root", password="xxx")
    Return session_id

User: Execute the ls command
AI: Call ssh_exec(session_id="xxx", command="ls -la")

User: Disconnect
AI: Call ssh_disconnect(session_id="xxx")

Development

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Development mode (hot reload)
npm run dev

# Build
npm run build

Limitations

🛡️ Security Precautions

⚠️ Important Note

1. Credential Protection: Passwords and private keys are only stored in memory and will not be persisted to disk.
2. Log Security: Passwords and private key contents will not be printed in the logs.
3. Session Cleanup: All sessions will be automatically cleaned up when the service is closed.
4. Command Limit: The command length is limited to 1000 characters to avoid abuse.
5. Output Limit: Output exceeding 25000 characters will be truncated.
6. Environment Variables: It is recommended to use private key authentication instead of passwords for greater security.
7. Configuration File Security: Do not commit configuration files containing passwords to version control.

Technical Stack

• Runtime: Node.js 18+
• Language: TypeScript 5
• MCP SDK: @modelcontextprotocol/sdk
• SSH Library: ssh2
• Parameter Validation: Zod
• Testing Framework: Vitest

📄 License

MIT License - See the LICENSE file for details.