SSH Server MCP

Remote SSH server control via Model Context Protocol (MCP).

This MCP server allows AI assistants (ChatGPT, Claude, etc.) to securely execute commands, read/write files, and manage your Linux servers via SSH.

Features

• Remote Command Execution: Execute shell commands on SSH servers
• File Management: Read and write files remotely
• Directory Listing: Browse remote directory structures
• System Information: Get OS, memory, disk, and CPU information
• Security: Built-in dangerous command blocking
• MCP Compatible: Works with ChatGPT, Claude Desktop, and other MCP clients

Available Tools

1. execute_command - Run shell commands on the remote server
2. read_file - Read file contents from the remote server
3. write_file - Write content to files on the remote server
4. list_directory - List directory contents with metadata
5. get_system_info - Get comprehensive system information
6. search - Search for commands and server information
7. fetch - Fetch information from server resources

Installation

1. Clone and Setup

git clone <your-repo>
cd ssh-server-connector
pip install -r requirements.txt

2. Configure Environment

Copy .env.example to .env and configure:

cp .env.example .env
nano .env

Required settings:

SSH_HOST=your-server.com
SSH_PORT=22
SSH_USERNAME=your_username

# Choose one authentication method:
# Option 1: Password
SSH_PASSWORD=your_password

# Option 2: SSH Key (recommended)
SSH_KEY_PATH=/path/to/private/key
SSH_KEY_PASSPHRASE=your_passphrase  # if key is encrypted

# MCP Server settings
MCP_HOST=0.0.0.0
MCP_PORT=8002

3. Run Locally

python server.py

Server will start on http://localhost:8002/mcp

Deployment

Deploy to Production Server

Option 1: Using systemd (Recommended)

Create a systemd service file:

sudo nano /etc/systemd/system/ssh-mcp.service

[Unit]
Description=SSH MCP Server
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/ssh-server-connector
Environment="PATH=/path/to/venv/bin"
ExecStart=/path/to/venv/bin/python server.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable ssh-mcp
sudo systemctl start ssh-mcp
sudo systemctl status ssh-mcp

Option 2: Using Docker

Create Dockerfile:

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["python", "server.py"]

Build and run:

docker build -t ssh-mcp .
docker run -d -p 8002:8002 --env-file .env --name ssh-mcp ssh-mcp

Nginx Reverse Proxy

Configure nginx for your domain:

server {
    listen 80;
    server_name your-domain.com;

    location /mcp {
        proxy_pass http://localhost:8002;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;

        # Streaming support
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400;
    }
}

Enable SSL with Let's Encrypt:

sudo certbot --nginx -d your-domain.com

Connect to MCP Clients

1. Get Your Server URL

After deployment, your MCP server URL will be:

https://your-domain.com/mcp

2. Add to MCP Clients

ChatGPT (Plus/Pro required):

1. Go to ChatGPT Settings → Developer → Custom connectors
2. Click "Add Connector"
3. Enter your MCP server URL: https://your-domain.com/mcp
4. Configure tools access
5. Save

Claude Desktop:

Edit your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ssh-server": {
      "url": "https://your-domain.com/mcp"
    }
  }
}

Via API:

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
  "model": "o4-mini-deep-research",
  "input": [{"role": "user", "content": [{"type": "input_text", "text": "Check disk usage on my server"}]}],
  "tools": [{
    "type": "mcp",
    "server_label": "ssh-server",
    "server_url": "https://your-domain.com/mcp",
    "allowed_tools": ["execute_command", "get_system_info"],
    "require_approval": "never"
  }]
}'

3. Test the Connection

Try these prompts:

• "Check my server disk usage"
• "List files in /var/log"
• "Show me system information"
• "Read the contents of /etc/hostname"
• "What processes are running on my server?"

Security Considerations

Built-in Security Features

1. Dangerous Command Blocking: Automatically blocks destructive commands like rm -rf /, mkfs, etc.
2. Output Size Limits: Prevents memory exhaustion from large outputs
3. Connection Timeouts: Commands timeout after 30 seconds
4. SSH Key Authentication: Supports key-based auth (more secure than passwords)

Recommended Security Practices

1. Use SSH Keys: Prefer key-based authentication over passwords
2. Firewall: Restrict MCP server access to trusted IPs only
3. HTTPS: Always use SSL/TLS in production
4. User Permissions: Run SSH with a limited user account (not root)
5. Monitor Logs: Regularly check logs for suspicious activity
6. Command Whitelist: Configure ALLOWED_COMMANDS in .env if needed

Firewall Example (ufw)

# Allow SSH from anywhere
sudo ufw allow 22/tcp

# Allow MCP server only from specific IPs (optional)
sudo ufw allow from YOUR_IP to any port 8002

# Enable firewall
sudo ufw enable

Troubleshooting

Connection Issues

# Check if server is running
curl http://localhost:8002/mcp

# Check logs
journalctl -u ssh-mcp -f

# Test SSH connection manually
ssh username@your-server.com

Permission Denied

Make sure SSH user has proper permissions:

# Check current user
whoami

# Add user to sudo group if needed
sudo usermod -aG sudo username

Environment Variables Reference

Variable	Required	Default	Description
SSH_HOST	Yes	-	SSH server hostname or IP
SSH_PORT	No	22	SSH server port
SSH_USERNAME	Yes	-	SSH username
SSH_PASSWORD	No*	-	SSH password (*required if no key)
SSH_KEY_PATH	No*	-	Path to private SSH key (*required if no password)
SSH_KEY_PASSPHRASE	No	-	SSH key passphrase if encrypted
MCP_HOST	No	0.0.0.0	MCP server bind address
MCP_PORT	No	8002	MCP server port
ALLOWED_COMMANDS	No	-	Comma-separated list of allowed commands
MAX_OUTPUT_SIZE	No	10000	Maximum output size in bytes

Development

Local Testing

# Install dependencies
pip install -r requirements.txt

# Run in development mode
python server.py

Test with MCP Inspector

npx @modelcontextprotocol/inspector python server.py

License

MIT

Support

For issues and questions, please open an issue on GitHub.