# 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:
```bash
git clone <repository-url>
cd ssh_mcp
```

2. Install dependencies:
```bash
uv sync
```

3. Test the installation:
```bash
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`:

```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`:

```python
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
```bash
# 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