# SSH Read-Only MCP Server

A secure Model Context Protocol (MCP) server that enables remote SSH command execution with strict read-only enforcement. Perfect for safely delegating SSH access to Claude while preventing accidental or malicious write operations.

## Features

✅ **Read-Only Command Enforcement** – Only allows safe, read-only commands  
✅ **SSH Connection Pooling** – Support multiple simultaneous connections  
✅ **Command Validation** – Blocks dangerous patterns and write operations  
✅ **Multicast Discovery** – Auto-announces on network for easy discovery  
✅ **Flexible Transport** – Stdio, HTTP, or Streamable-HTTP modes  
✅ **Comprehensive Logging** – Full audit trail in `ssh_mcp.log`  
✅ **Environment Configuration** – Fully configurable via .env

## Installation

### Prerequisites

- Python 3.8+
- `uv` package manager

### Setup

```bash
# Clone or create project directory
mkdir ssh-mcp-server
cd ssh-mcp-server

# Initialize uv project (if needed)
uv init

# Install dependencies
uv pip install fastmcp paramiko python-dotenv
```

Or use `pyproject.toml`:

```toml
[project]
name = "ssh-mcp-server"
version = "0.1.0"
dependencies = [
    "fastmcp>=0.1.0",
    "paramiko>=3.0.0",
    "python-dotenv>=1.0.0",
]
```

Then install:

```bash
uv sync
```

## Configuration

Create a `.env` file in the project root:

```env
# Transport mode: stdio (default), http, or streamable-http
MCP_TRANSPORT=stdio

# Server identification
MCP_SERVER_NAME=SSH Read-Only MCP Server

# HTTP mode settings (if using http/streamable-http)
MCP_HOST=0.0.0.0
MCP_PORT=3000

# Multicast discovery
MCP_ENABLE_BROADCAST=true
MCP_BROADCAST_INTERVAL=30
```

### Environment Variables

| Variable                 | Default                    | Description                                                    |
| ------------------------ | -------------------------- | -------------------------------------------------------------- |
| `MCP_TRANSPORT`          | `stdio`                    | Communication transport: `stdio`, `http`, or `streamable-http` |
| `MCP_SERVER_NAME`        | `SSH Read-Only MCP Server` | Display name for the server                                    |
| `MCP_HOST`               | `0.0.0.0`                  | Bind address for HTTP mode                                     |
| `MCP_PORT`               | `3000`                     | Port for HTTP mode                                             |
| `MCP_ENABLE_BROADCAST`   | `true`                     | Enable multicast discovery announcements                       |
| `MCP_BROADCAST_INTERVAL` | `30`                       | Seconds between broadcast announcements                        |

## Usage

### Start the Server

**Stdio mode (default):**

```bash
uv run ssh_readonly_fastmcp_mcast.py
```

**HTTP mode with multicast discovery:**

```bash
MCP_TRANSPORT=http MCP_PORT=3000 uv run ssh_readonly_fastmcp_mcast.py
```

**HTTP mode without broadcasting:**

```bash
MCP_ENABLE_BROADCAST=false MCP_TRANSPORT=http MCP_PORT=3000 uv run ssh_readonly_fastmcp_mcast.py
```

### Available Tools

#### 1. `ssh_connect`

Establish an SSH connection to a remote machine.

**Parameters:**

- `host` (required) – Remote host IP or hostname
- `username` (required) – SSH username
- `port` (optional, default: 22) – SSH port
- `key_filename` (optional) – Path to private key file (recommended)
- `password` (optional) – SSH password (fallback)

**Example:**

```
Connect to 192.168.1.100 as user 'admin' with private key
host: 192.168.1.100
username: admin
key_filename: /home/user/.ssh/id_rsa
```

#### 2. `ssh_execute`

Execute a read-only command on the connected remote machine.

**Parameters:**

- `host` (required) – Remote host (must be connected first)
- `username` (required) – SSH username
- `command` (required) – Read-only command to execute
- `port` (optional, default: 22) – SSH port

**Example:**

```
Run 'ls -la /home' on connected server
host: 192.168.1.100
username: admin
command: ls -la /home
```

#### 3. `ssh_disconnect`

Close an SSH connection.

**Parameters:**

- `host` (required) – Remote host
- `username` (required) – SSH username
- `port` (optional, default: 22) – SSH port

#### 4. `ssh_list_connections`

View all active SSH connections.

**Parameters:** None

#### 5. `ssh_get_allowed_commands`

Retrieve the list of allowed read-only commands.

**Parameters:** None

## Allowed Commands

The server permits the following read-only operations:

- **File operations:** `cat`, `ls`, `file`, `head`, `tail`, `find`, `locate`
- **System info:** `ps`, `top`, `df`, `du`, `free`, `uname`, `hostname`, `uptime`
- **Network:** `netstat`, `ss`, `ifconfig`, `ip`, `curl`, `wget`, `dig`, `nslookup`, `ping`, `traceroute`
- **Process management:** `lsof`, `systemctl`, `service`
- **Text processing:** `grep`, `awk`, `sed`, `wc`
- And many more read-only utilities

**Blocked operations:** `rm`, `mv`, `cp`, `chmod`, `chown`, `mkdir`, `touch`, `kill`, `shutdown`, `reboot`, `sudo`, and any write/modify commands.

## Multicast Discovery

When running in HTTP mode with broadcasting enabled, the server announces itself on the multicast group:

- **Address:** `239.255.255.250`
- **Port:** `5353`
- **Interval:** Configurable (default: 30 seconds)

Discovery announcement includes:

- Server UUID
- Server name
- Local IP and port
- Transport type
- Protocol version

## Logging

All activity is logged to `ssh_mcp.log`:

```
2025-10-17 10:30:45,123 [INFO] ssh_mcp - Starting MCP server with transport=http
2025-10-17 10:30:46,456 [INFO] ssh_mcp - Starting multicast broadcaster on 239.255.255.250:5353
2025-10-17 10:30:47,789 [INFO] ssh_mcp - Successfully connected to admin@192.168.1.100:22
```

## Security Considerations

🔒 **Read-Only Enforcement:**

- Only whitelisted commands are allowed
- Dangerous patterns (pipes, redirects, subshells) are blocked
- Write operations are prevented at the command level

⏱️ **Timeouts:**

- 30-second execution timeout per command
- Prevents hanging commands from blocking the server

🔐 **Authentication:**

- SSH key authentication recommended over passwords
- Passwords stored in memory only, never persisted

📋 **Audit Trail:**

- All connections and commands are logged
- Review `ssh_mcp.log` for security audits

## Troubleshooting

### Connection Refused

```
Error: Connection failed: [Errno 111] Connection refused
```

- Verify the remote host is reachable: `ping <host>`
- Check SSH is running on the remote machine
- Verify port number (default 22)

### Authentication Failed

```
Error: Connection failed: Authentication failed
```

- Verify username is correct
- For key auth: check key file path and permissions (`chmod 600`)
- For password auth: verify credentials
- Ensure SSH public key is authorized on remote (`~/.ssh/authorized_keys`)

### Command Not Allowed

```
Error: Command not allowed for security reasons
```

- The command contains a blocked pattern or is not in the allowed list
- Use `ssh_get_allowed_commands` to see permitted commands
- For write operations, use SSH directly instead

### Broadcast Not Working

- Verify `MCP_ENABLE_BROADCAST=true`
- Check network supports multicast (most corporate networks block it)
- Verify firewall allows UDP on port 5353
- Check `ssh_mcp.log` for broadcast errors

## Development

### Running in Debug Mode

```bash
DEBUG=true uv run ssh_readonly_fastmcp_mcast.py
```

### Testing

```bash
# Test connection
uv run -c "from ssh_readonly_fastmcp_mcast import is_command_safe; print(is_command_safe('ls -la'))"

# Should print: True

# Test blocked command
uv run -c "from ssh_readonly_fastmcp_mcast import is_command_safe; print(is_command_safe('rm -rf /'))"

# Should print: False
```

## Project Structure

```
ssh-mcp-server/
├── ssh_readonly_fastmcp_mcast.py    # Main server implementation
├── .env                        # Configuration file
├── .env.example               # Configuration template
├── ssh_mcp.log                # Server logs (auto-generated)
├── pyproject.toml             # Project metadata
└── README.md                  # This file
```

## API Response Format

All tools return consistent JSON responses:

**Success:**

```json
{
  "status": "success",
  "host": "192.168.1.100",
  "command": "ls -la /home",
  "exit_code": 0,
  "output": "total 24\ndrwxr-xr-x 3 root root 4096...",
  "error": null
}
```

**Error:**

```json
{
  "status": "error",
  "message": "Command not allowed for security reasons",
  "reason": "Only read-only commands are permitted"
}
```

## License

MIT

## Contributing

Contributions welcome! Please ensure:

- All changes maintain read-only enforcement
- Code is logged appropriately
- Tests pass for security validations

## Support

For issues or questions:

1. Check `ssh_mcp.log` for error details
2. Review the Troubleshooting section
3. Verify environment configuration
4. Check network connectivity to remote hosts