🔗 RemoteShell MCP

一个 Model Context Protocol (MCP) 服务器，使 LLM 能够安全地管理和执行远程 SSH 服务器上的命令。

✨ 功能

• 🔐 安全凭据管理 - 保存一次 SSH 服务器配置，无需重新输入凭据

• 💻 远程命令执行 - 远程执行非交互式 shell 命令

• 📁 文件操作 - 通过 SFTP 上传/下载文件

• 🤖 LLM 驱动 - 基于 FastMCP 和 Paramiko 构建

Related MCP server: SSH MCP Server

🚀 安装

RemoteShell 是一个通过 PyPI 分发的 stdio MCP 服务器。直接使用 uvx 运行它 — 无需安装步骤。然后将服务器注册到你的 AI 编码代理：

Claude Code

claude mcp add remoteshell --scope user -- uvx remoteshell-mcp

Codex

codex mcp add remoteshell -- uvx remoteshell-mcp

其他代理 — 点击对应的代理以展开 👇

cursor mcp add remoteshell -- uvx remoteshell-mcp

编辑 ~/.gemini/config/mcp_config.json（全局）或 .agents/mcp_config.json（项目）：

{
  "mcpServers": {
    "remoteshell": {
      "command": "uvx",
      "args": ["remoteshell-mcp"]
    }
  }
}

或者在 Antigravity TUI 中打开 MCP Servers 视图并运行 /mcp 命令。

opencode mcp add

选择 local，然后输入 uvx remoteshell-mcp。

编辑 ~/.hermes/config.yaml：

mcp_servers:
  remoteshell:
    command: "uvx"
    args: ["remoteshell-mcp"]

在 Hermes TUI 中运行 /reload-mcp 以加载新服务器。

编辑 ~/.openclaw/openclaw.json：

{
  "mcp": {
    "servers": {
      "remoteshell": {
        "command": "uvx",
        "args": ["remoteshell-mcp"]
      }
    }
  }
}

或者运行 openclaw configure 通过交互式向导添加它。

将此添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "remoteshell": {
      "command": "uvx",
      "args": ["remoteshell-mcp"]
    }
  }
}

📖 使用

入门很简单！你可以选择：

1. 🤖 让 LLM 为你配置 - 只需告诉 LLM 你的主机、用户名、密码等，并让它设置服务器配置

2. ⚙️ 手动配置 - 直接编辑位于 ~/.config/remoteshell/hosts.json 的配置文件

💾 配置与存储

RemoteShell 将你的服务器配置安全存储在：

~/.config/remoteshell/hosts.json

🔧 配置管理

• LLM 管理：LLM 使用 save_server 和 remove_server 工具自动管理此文件

• 手动编辑：你也可以直接编辑 JSON 文件以进行高级配置

📋 示例配置

{
  "version": 1,
  "servers": {
    "production-server": {
      "host": "1.2.3.4",
      "user": "root",
      "port": 22,
      "auth_type": "password",
      "password": "your_secure_password",
      "last_connected": null
    },
    "staging-server": {
      "host": "staging.example.com",
      "user": "ubuntu",
      "port": 22,
      "auth_type": "private_key",
      "private_key": "~/.ssh/id_rsa",
      "last_connected": "2025-01-01T00:00:00+00:00"
    }
  }
}

🔒 安全说明

在 POSIX 系统上，保护你的配置文件：

chmod 600 ~/.config/remoteshell/hosts.json

🛠️ 可用工具

RemoteShell 提供以下 MCP 工具用于远程服务器管理：

📋 list_servers()

用途：显示所有已保存的服务器配置及其连接状态和最后活动时间。

使用时机：

• 用户要求“连接到服务器”或“显示机器”

• 未提供特定的 connection_id

• 需要查看可用的服务器

示例：“显示我已配置了哪些服务器” → 返回所有已保存服务器及其在线状态的列表

💾 save_server(connection_id, host, user, auth_type, credential, port)

用途：创建或更新带有身份验证凭据的服务器配置。

参数：

• connection_id：服务器的唯一标识符（例如，“production”、“staging”）

• host：服务器主机名或 IP 地址

• user：SSH 用户名

• auth_type："password" 或 "private_key"

• credential：

  • 对于 password：明文密码字符串

  • 对于 private_key：文件路径（例如，~/.ssh/id_rsa）或 PEM 密钥内容

• port：SSH 端口（可选；默认为 22，如果省略则保留已保存的端口）

使用时机：

• 添加新的服务器配置

• 在身份验证失败后更新凭据

• 更改服务器连接详情

🗑️ remove_server(connection_id)

用途：从存储中永久删除服务器配置。

使用时机：

• 用户明确要求删除或忘记服务器

• 服务器不再可访问或不再需要

⚠️ 警告：此操作无法撤销

⚡ execute_command(connection_id, command)

用途：远程执行非交互式 shell 命令并返回结果。

返回：stdout、stderr 和 exit_code

使用时机：

• 运行系统命令、脚本或实用程序

• 检查服务器状态、磁盘使用情况、进程列表

• 文件操作、包管理等

不应使用的情况：

• 交互式程序（vim、htop、top）

• 需要手动输入的命令（[Y/n] 提示）- 除非使用类似 -y 的标志

示例：execute_command(connection_id="production", command="df -h")

📤 upload_file(connection_id, local_path, remote_path)

用途：通过 SFTP 将文件从本地计算机上传到远程服务器。

参数：

• local_path：本地计算机上文件的路径

• remote_path：远程服务器上的目标路径

说明：

• 如果 remote_path 是目录，则保留原始文件名

• 如果省略 local_path，服务器会选择默认路径并在响应中返回

📥 download_file(connection_id, remote_path, local_path)

用途：通过 SFTP 将文件从远程服务器下载到本地计算机。

参数：

• remote_path：远程服务器上文件的路径

• local_path：本地计算机上的目标路径

说明：

• 如果省略 local_path，默认路径为：~/.config/remoteshell/downloads/<connection_id>/<basename>

🧪 开发

本地开发设置

对于本地开发，请使用此 MCP 配置：

{
  "mcpServers": {
    "remoteshell": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/remoteShell-mcp", "run", "remoteshell-mcp"]
    }
  }
}

运行测试

uv run pytest