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 package manager
• Claude Code CLI

---

Installation

No cloning required. Add the following to your project's .mcp.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:

{
  "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:

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