SSH MCP Server

Advanced SSH Session Manager for Model Context Protocol (MCP) with multi-session support and connection monitoring.

Features

• Multi-Session Management: Create and manage multiple SSH connections simultaneously
• Session Monitoring: Automatic connection health checks and timeout management
• Command Execution: Execute commands on remote servers with timeout control
• Session Persistence: Maintain long-running SSH sessions with metadata tracking
• Automatic Cleanup: Intelligent session cleanup based on usage and timeouts

Installation

Prerequisites

• Python 3.11+
• UV package manager
• Claude Desktop

Setup with UV

1. Clone or download this project:

git clone <repository-url>
cd ssh_mcp

2. Install dependencies:

uv sync

3. Test the installation:

uv run python main.py

Claude Desktop Configuration

1. Locate Claude Desktop Config File

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

2. Add MCP Server Configuration

Add the following configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "ssh-session-manager": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/ssh_mcp",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "PYTHONPATH": "path/to/ssh_mcp"
      }
    }
  }
}

Note: Replace path/to/ssh_mcp with the actual path to your project directory.

3. Restart Claude Desktop

After saving the configuration, restart Claude Desktop to load the MCP server.

Available Tools

ssh_connect

Create a new SSH connection session.

Parameters:

• host (string): SSH server hostname or IP address
• username (string): SSH username
• password (string): SSH password
• port (int, optional): SSH port (default: 22)
• session_name (string, optional): Custom session name

Example:

Connect to my server using ssh_connect with host="192.168.1.100", username="admin", password="mypassword"

ssh_execute

Execute a command in an existing SSH session.

Parameters:

• session_id (string): ID of the SSH session
• command (string): Command to execute
• timeout (int, optional): Command timeout in seconds (default: 30)

Example:

Execute "ls -la" command in session "ssh_12345678"

ssh_list_sessions

List all active SSH sessions.

Example:

Show me all active SSH sessions

ssh_session_info

Get detailed information about a specific SSH session.

Parameters:

• session_id (string): ID of the SSH session

Example:

Get information about session "ssh_12345678"

ssh_close_session

Close a specific SSH session.

Parameters:

• session_id (string): ID of the SSH session to close

Example:

Close SSH session "ssh_12345678"

ssh_close_all_sessions

Close all active SSH sessions.

Example:

Close all SSH sessions

Configuration Options

Session Manager Settings

You can modify the session manager settings in main.py:

ssh_manager = SSHSessionManager(
    max_sessions=5,        # Maximum number of concurrent sessions
    session_timeout=600    # Session timeout in seconds (10 minutes)
)

Security Considerations

• Host Key Verification: Currently disabled for development. Enable proper host key verification for production use.
• Password Storage: Passwords are not stored persistently but remain in memory during the session.
• Network Security: Use this tool only on trusted networks.

Usage Examples

Basic SSH Connection

Connect to server 192.168.1.100 with username "admin" and password "mypass"

Execute Multiple Commands

1. Connect to my server at example.com with username "user" and password "pass"
2. Execute "whoami" command
3. Execute "df -h" command  
4. Show session information

Session Management

1. List all active sessions
2. Close session with oldest connection
3. Show remaining sessions

Dependencies

• asyncssh>=2.21.0: Asynchronous SSH client library
• mcp[cli]>=1.9.2: Model Context Protocol framework
• paramiko>=3.5.1: SSH client library (backup/compatibility)

Development

Project Structure

ssh_mcp/
├── main.py              # Main MCP server implementation
├── pyproject.toml       # Project configuration and dependencies
├── uv.lock             # Dependency lock file
├── README.md           # This file
└── run_mcp.bat         # Windows batch script for easy execution

Running in Development Mode

# Run the MCP server directly
uv run python main.py

# Or use the batch script (Windows)
run_mcp.bat

Adding New Features

1. Modify the SSHSessionManager class in main.py
2. Add new MCP tools using the @mcp.tool() decorator
3. Update this README with new tool documentation

Troubleshooting

Connection Issues

• Verify SSH server is accessible and credentials are correct
• Check firewall settings and network connectivity
• Ensure SSH service is running on the target server

Claude Desktop Integration

• Confirm UV is installed and accessible from system PATH
• Verify the project path in the configuration is correct
• Check Claude Desktop logs for error messages
• Restart Claude Desktop after configuration changes

Session Timeouts

• Increase session_timeout value in the session manager
• Check network stability for long-running sessions
• Monitor session activity with ssh_list_sessions

License

This project is open source. Please refer to the license file for more information.

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

Changelog

v0.1.0

• Initial release
• Multi-session SSH management
• Basic command execution
• Session monitoring and cleanup
• Claude Desktop integration