SSH/SFTP MCP Server

English | 中文

A Model Context Protocol (MCP) server that enables AI assistants like Claude to execute SSH commands and perform SFTP file operations on remote servers.

Features

• Server Configuration Management - Define servers in config files or environment variables
• Connection Testing - Test server connectivity before establishing sessions
• SSH Command Execution - Run commands remotely with optional sudo support
• SFTP File Operations - Upload, download, list, create, and delete files/directories
• Session Management - Auto-cleanup of idle sessions, connection pooling
• Multiple Auth Methods - Password and private key authentication

Installation

Using npx (Recommended)

npx ssh-client-mcp

Using npm

npm install -g ssh-client-mcp

From Source

git clone https://github.com/veithly/ssh-client-mcp.git
cd ssh-client-mcp
npm install
npm run build

Quick Start

Configure Claude Desktop

Add to your Claude Desktop configuration file:

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

Option 1: CLI Arguments (Recommended)

Configure server directly via command line arguments:

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": [
        "ssh-client-mcp",
        "--host", "192.168.1.100",
        "--user", "admin",
        "--password", "your-password"
      ]
    }
  }
}

With private key authentication:

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": [
        "ssh-client-mcp",
        "--host", "192.168.1.100",
        "--user", "admin",
        "--key", "~/.ssh/id_rsa"
      ]
    }
  }
}

With private key + passphrase:

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": [
        "ssh-client-mcp",
        "--host", "192.168.1.100",
        "--user", "admin",
        "--key", "~/.ssh/id_rsa",
        "--passphrase", "your-key-passphrase"
      ]
    }
  }
}

Available CLI Arguments:

Option 2: Config File

Create a servers.json file in the working directory:

{
  "servers": [
    {
      "id": "my-server",
      "name": "My Server",
      "host": "192.168.1.100",
      "port": 22,
      "username": "admin",
      "password": "your-password"
    }
  ],
  "defaultServer": "my-server"
}

Option 3: Environment Variables

SSH_SERVER_DEV_HOST=192.168.1.100
SSH_SERVER_DEV_PORT=22
SSH_SERVER_DEV_USERNAME=admin
SSH_SERVER_DEV_PASSWORD=your-password
SSH_SERVER_DEV_NAME=Development Server

Then restart Claude Desktop to load the MCP server.

Available Tools (18 total)

Server Management

Connection Management

Command Execution

File Operations (SFTP)

Usage Examples

List Configured Servers

Tool: ssh_list_servers
Arguments: {}

Test Connection

Tool: ssh_test_connection
Arguments: {
  "serverId": "my-server"
}

Connect to Server

Tool: ssh_connect_by_id
Arguments: {
  "serverId": "my-server"
}

Execute Command

Tool: ssh_exec
Arguments: {
  "sessionId": "<session-id>",
  "command": "ls -la /home"
}

Upload File

Tool: sftp_upload
Arguments: {
  "sessionId": "<session-id>",
  "localPath": "/local/path/file.txt",
  "remotePath": "/remote/path/file.txt"
}

Download File

Tool: sftp_download
Arguments: {
  "sessionId": "<session-id>",
  "remotePath": "/remote/path/file.txt",
  "localPath": "/local/path/file.txt"
}

Configuration Options

Environment Variables

Server Configuration Fields

*Either password or privateKeyPath must be provided.

Security Considerations

• Sessions auto-expire after 30 minutes of inactivity
• Maximum session limit prevents resource exhaustion
• Credentials are not stored persistently
• Sudo passwords are not logged
• Use SSH keys instead of passwords when possible

Development

# Clone the repository
git clone https://github.com/veithly/ssh-client-mcp.git
cd ssh-client-mcp

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Clean build
npm run clean

Project Structure

ssh-client-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types.ts              # Type definitions
│   ├── SessionManager.ts     # SSH session lifecycle
│   ├── SSHExecutor.ts        # Command execution
│   ├── SFTPOperations.ts     # SFTP file operations
│   ├── ConnectionTester.ts   # Connection testing
│   ├── config/
│   │   ├── ConfigManager.ts  # Configuration management
│   │   ├── types.ts          # Config types
│   │   └── index.ts          # Config exports
│   └── tools/
│       ├── connection.ts     # Connection tools
│       ├── command.ts        # Command tools
│       ├── file.ts           # File tools
│       ├── server.ts         # Server management tools
│       └── index.ts          # Tool exports
├── servers.example.json      # Example server config
├── .env.example              # Example environment config
├── package.json
├── tsconfig.json
└── README.md

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

MIT © 2024

Acknowledgments

• Model Context Protocol - The MCP SDK
• ssh2 - SSH2 client library for Node.js

Made for Claude AI