Skip to main content
Glama
ai-ssh-mcp

ai-ssh-mcp

by guozhiwei01

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


Related MCP server: MCP SSH Server with Streamable HTTP

Prerequisites


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

Available Tools

6 tools
batch_execA
在多台服务器上同时执行同一命令。

参数:
- command: 要执行的 Shell 命令
- tag: 按标签筛选服务器,如"prod"、"api"
- servers: 指定服务器名列表,如["生产-API主服务器", "测试环境"]
- confirmed: 写操作时需确认后传 True
tag 和 servers 至少填一个。

Inputs: command (required), tag, servers, confirmed. Returns: result

exec_commandB
在指定服务器上执行任意 Shell 命令。

参数:
- server: 服务器中文名
- command: 要执行的 Shell 命令
- confirmed: 写操作时需用户确认后传 True,默认 False

Inputs: server (required), command (required), confirmed. Returns: result

list_serversA

列出所有配置的服务器及其基本信息(名称、IP、标签、项目)。

Inputs: no named parameters. Returns: result

read_logsA
读取指定服务器上某个项目的日志文件。

参数:
- server: 服务器中文名,如"生产-API主服务器"
- project: 项目名,如"shop"。服务器只有一个项目时可省略
- log_type: "app"(默认,Laravel log)或 "nginx"(nginx error log)
- lines: 读取最后 N 行,默认 100
- keyword: 关键词过滤,只返回包含该词的行,如"ERROR"

Inputs: server (required), lines, keyword, project, +1 more. Returns: result

service_statusA
检查服务器上关键服务的运行状态和系统资源。

参数:
- server: 服务器中文名
- services: 指定要检查的服务列表(可选),默认检查 nginx/php-fpm/mysql/redis 及系统资源

Inputs: server (required), services. Returns: result

transfer_fileA
在本地和服务器之间传输文件(SFTP)。

参数:
- server: 服务器中文名
- direction: "upload"(上传)或 "download"(下载)
- local_path: 本地文件路径
- remote_path: 服务器上的文件路径
- confirmed: 上传属于写操作,需确认后传 True

Inputs: server (required), direction (required), local_path (required), remote_path (required), +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 6 tools

    Disambiguation5/5

    每个工具都有明确且互不重叠的用途:列出服务器、单机执行命令、批量执行命令、读取日志、检查服务状态、传输文件。描述清晰,代理可以轻松区分。

    Naming Consistency4/5

    大多数工具遵循 verb_noun 模式(如 exec_command, list_servers, read_logs, transfer_file),但 batch_exec 是 adj_verb 形式,service_status 是 noun_noun,存在小偏差,整体仍可接受。

    Tool Count5/5

    6个工具覆盖了远程服务器管理的基本需求:执行命令、批量操作、日志、状态、文件传输和服务器列表。数量合理,没有冗余或不足。

    Completeness3/5

    覆盖了核心运维任务(命令执行、日志、文件传输、状态),但缺少服务启停、配置编辑、用户管理等常见操作,存在明显缺口。

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables SSH remote access to servers through Claude, allowing users to execute commands, transfer files via SFTP, and manage multiple remote connections using natural language.
      12
      9
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Connects Claude to remote servers via SSH to execute commands, manage files, and browse directories. It allows users to add, edit, and switch between multiple server configurations through natural language conversations.
      -