# Ubuntu SSH MCP Server

An MCP server that lets Claude Code connect to Ubuntu servers over SSH to **manage, maintain, and secure** them — all from a natural language conversation.

---

## Features

| Category | Tools |
|---|---|
| **Connection** | Connect/disconnect servers, list active sessions |
| **Commands** | Run shell commands, sudo commands |
| **System Info** | OS/CPU/RAM/disk overview, process list, disk usage |
| **Packages** | apt update, upgrade, install, remove |
| **Services** | Start/stop/restart/enable systemd services |
| **Logs** | journalctl, tail log files |
| **Files** | Read, write, list remote files |
| **Security Audit** | Open ports, SUID files, sudo rights, failed logins |
| **Firewall (UFW)** | Status, add/delete rules, enable/disable |
| **SSH Hardening** | Disable root login, password auth, MaxAuthTries |
| **Users** | List, create, delete users; add SSH public keys |
| **Fail2ban** | Jail status, unban IPs |
| **Cron** | List cron jobs |
| **Network** | Interface info, routing, ping |

---

## Requirements

- Node.js 18+
- Claude Code (`npm install -g @anthropic-ai/claude-code`)

---

## Installation

```bash
# 1. Clone / copy this folder somewhere permanent
cd ~/ubuntu-ssh-mcp
npm install

# 2. Register with Claude Code (global scope — available in all projects)
claude mcp add ubuntu-ssh-mcp -- node /ABSOLUTE/PATH/TO/ubuntu-ssh-mcp/index.js

# Verify it's registered
claude mcp list
```

### Alternative: Project-level config

Create or edit `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "ubuntu-ssh-mcp": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/ubuntu-ssh-mcp/index.js"]
    }
  }
}
```

---

## Usage Examples

Once Claude Code is running with the MCP server connected, just talk to it:

```
> Connect to my server at 192.168.1.10 as ubuntu using my key at ~/.ssh/id_rsa, call it "prod"

> Show me the system info for prod

> Check what security updates are available on prod

> Run a full security audit on prod

> Harden the SSH config on prod — make sure I have key auth working first

> Enable UFW on prod and allow only ports 22, 80, and 443

> Show the last 100 lines of the nginx error log on prod

> List all users on prod and check if any have unexpected sudo access

> Install fail2ban on prod and check the sshd jail status
```

---

## Security Notes

- **Use SSH key auth** — avoid passing passwords where possible.
- **`sudo_password`** is passed as a parameter; Claude Code stores no secrets. Use `NOPASSWD` sudoers for a CI/automation account if you prefer not to pass passwords.
- **`harden_ssh`** will restart sshd — ensure key-based auth is working before calling it or you may lock yourself out.
- Connections persist for the life of the Claude Code session and are cleaned up on exit.
- The server runs locally via stdio — no network ports are opened by the MCP server itself.

---

## Tool Reference

### Connection
| Tool | Description |
|---|---|
| `ssh_connect` | Connect to a server |
| `ssh_disconnect` | Disconnect from a server |
| `ssh_list_connections` | List active connections |

### Execution
| Tool | Description |
|---|---|
| `ssh_exec` | Run a shell command |
| `ssh_sudo` | Run a command with sudo |

### System
| Tool | Description |
|---|---|
| `system_info` | OS, CPU, RAM, disk, uptime |
| `list_processes` | Top processes by CPU/mem |
| `check_disk_usage` | Disk usage breakdown |
| `network_info` | Interfaces, routing, connections |
| `ping_from_server` | Ping a host from the server |

### Packages
| Tool | Description |
|---|---|
| `apt_update` | Update package index |
| `apt_upgrade` | Upgrade all packages |
| `apt_install` | Install packages |
| `apt_remove` | Remove packages |

### Services
| Tool | Description |
|---|---|
| `service_status` | Check service status |
| `service_control` | Start/stop/restart/enable/disable |
| `list_services` | List all/running/failed services |

### Logs
| Tool | Description |
|---|---|
| `view_logs` | journalctl for service or system |
| `tail_log_file` | Last N lines of any log file |

### Files
| Tool | Description |
|---|---|
| `read_file` | Read a remote file |
| `write_file` | Write a remote file |
| `list_directory` | List directory contents |

### Security
| Tool | Description |
|---|---|
| `security_audit` | Full security audit |
| `check_updates_security` | Security-only apt updates |
| `harden_ssh` | Apply SSH hardening |
| `ufw_status` | UFW firewall status |
| `ufw_rule` | Add/delete UFW rules |
| `ufw_enable_disable` | Enable/disable UFW |
| `fail2ban_status` | Fail2ban jail status |
| `fail2ban_unban` | Unban an IP |

### Users
| Tool | Description |
|---|---|
| `user_list` | List system users |
| `user_create` | Create a user |
| `user_delete` | Delete a user |
| `add_authorized_key` | Add SSH public key |
| `cron_list` | List cron jobs |