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

Or use pyproject.toml:

Then install:

Configuration

Create a .env file in the project root:

Environment Variables

Usage

Start the Server

Stdio mode (default):

HTTP mode with multicast discovery:

HTTP mode without broadcasting:

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:

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:

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:

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

• Verify the remote host is reachable: ping <host>

• Check SSH is running on the remote machine

• Verify port number (default 22)

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

• 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

Testing

Project Structure

API Response Format

All tools return consistent JSON responses:

Success:

Error:

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