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:

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

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