# ai-ssh-mcp

Natural language SSH server management via Claude Code.

Stop copying commands from AI to your terminal. This MCP server lets Claude Code connect directly to your servers — read logs, check services, run commands, transfer files — all in one conversation.

---

## Features

- **Read logs** — tail Laravel / nginx logs with keyword filtering
- **Service status** — check nginx, php-fpm, mysql, redis and system resources (memory, disk, load)
- **Execute commands** — run any shell command with a write-operation confirmation step
- **File transfer** — upload / download files via SFTP
- **Batch execute** — run a command across multiple servers in parallel, filtered by tag
- **Safety layer** — blacklist for destructive commands, confirmation prompts for write ops, operation log
- **Fuzzy server matching** — refer to servers by partial name (e.g. "生产API" matches "生产-API主服务器")
- **Connection reuse** — SSH connections are cached for the session

---

## Prerequisites

- Python 3.11+
- [uv](https://github.com/astral-sh/uv) package manager
- [Claude Code](https://claude.ai/code) CLI

---

## Installation

No cloning required. Add the following to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "ai-ssh-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/guozhiwei01/ai-ssh-mcp", "ai-ssh-mcp"]
    }
  }
}
```

Restart Claude Code. On first run, the config directory is created automatically at `~/.config/ai-ssh-mcp/` with a template `servers.json` copied in.

---

## Configuration

### 1. Server list (`~/.config/ai-ssh-mcp/servers.json`)

The template is created automatically on first run. Edit it to add your servers:

```json
{
  "servers": [
    {
      "name": "生产-API主服务器",
      "host": "47.x.x.1",
      "port": 22,
      "username": "root",
      "auth": {
        "type": "privateKey",
        "path": "~/.ssh/id_rsa"
      },
      "tags": ["prod", "api"],
      "projects": [
        {
          "name": "shop",
          "path": "/var/www/shop",
          "log": "/var/www/shop/storage/logs/laravel.log",
          "nginx_log": "/var/log/nginx/shop_error.log",
          "fpm_pool": "shop"
        }
      ]
    }
  ]
}
```

Key fields:

| Field | Description |
|-------|-------------|
| `name` | Display name (Chinese-friendly). Claude uses this to identify servers. |
| `host` | IP address or hostname |
| `port` | SSH port, default `22` |
| `username` | SSH login user |
| `auth.type` | `privateKey` or `password` |
| `auth.path` | Path to private key file (supports `~`) |
| `auth.env_key` | For password auth: the `.env` variable name that holds the password |
| `tags` | Used for batch operations, e.g. `["prod", "api"]` |
| `projects` | List of deployed projects with log paths |

### 2. Credentials (`~/.config/ai-ssh-mcp/.env`)

For password-authenticated servers, create `~/.config/ai-ssh-mcp/.env`:

```env
SERVER_生产数据库_PASSWORD=your_password_here
```

> Private key auth needs no `.env` entries — just make sure the key file exists at the configured path.

---

## Usage Examples

Once connected, talk to Claude naturally:

> "列出所有服务器"

> "看一下生产 API 服务器上 shop 项目最近的报错"

> "检查生产数据库的服务状态"

> "在测试环境重启 nginx"  *(Claude will ask for confirmation)*

> "所有 prod 服务器的磁盘使用情况"

> "把本地的 config.php 上传到生产-API主服务器的 /var/www/shop/config.php"

---

## Available Tools

| Tool | Description |
|------|-------------|
| `list_servers` | List all configured servers |
| `read_logs` | Read project log files (app or nginx), with optional keyword filter |
| `service_status` | Check service health and system resources |
| `exec_command` | Run any shell command (write ops require confirmation) |
| `transfer_file` | Upload or download files via SFTP |
| `batch_exec` | Run a command on multiple servers in parallel |

---

## Security

- **Blacklist**: `rm -rf /`, `mkfs`, `dd if=...of=/dev`, `shutdown`, `reboot`, `halt`, `poweroff` are always blocked.
- **Confirmation**: Any write operation (restart, kill, file modification, package install, etc.) returns a confirmation prompt before executing.
- **Operation log**: All executed commands are recorded in `~/.config/ai-ssh-mcp/operation.log` — format: `timestamp | server | user | command | exit_code`.
- **Secrets**: `servers.json` and `.env` live in your home directory and are never part of this repo.

---

## License

MIT