AI导哈

远程Shell命令执行服务

一个通过SSH在预配置的远程机器上执行shell命令的AI代理服务，支持配置验证、命令输出流式传输和遥测记录。

  • by haynb
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 haynb/remote-ssh-mcp

使用说明

远程服务器mcp

一种模型上下文协议（MCP）服务器，允许AI代理通过SSH在预配置的远程机器上执行shell命令。它预先验证配置，流式传输命令输出，并记录遥测数据，以便未来的护栏可以插入，而无需重写核心传输层。

先决条件

  • Node.js 20+
  • 远程SSH主机配置了运行MCP服务器的计算机可访问的凭据

安装

npm install

配置

默认情况下，服务器在以下位置查找TOML文件 ~/.config/remote-server-mcp/config.toml.用覆盖路径 REMOTE_SERVER_MCP_CONFIG 环境变量（如果需要）。

示例 config.toml:

[[hosts]]
alias = "staging-web"
host = "staging.example.com"
username = "deploy"
auth.type = "ssh-key"
auth.privateKeyPath = "/Users/me/.ssh/id_ed25519"
knownHostsPath = "/Users/me/.ssh/known_hosts"
timeoutMs = 60000

支持的身份验证策略：

  • ssh-key –从磁盘加载私钥（可选 passphrasePrompt 阅读 REMOTE_SERVER_MCP_PASSPHRASE_<ALIAS> 环境变量）
  • ssh-agent –使用当前的SSH代理(SSH_AUTH_SOCK)
  • credential-command –运行一个shell命令，将密码打印到stdout

文件更改时，配置会自动热重新加载。

运行服务器

npm run build
npm start

在开发过程中，您可以直接运行TypeScript源代码：

npm run dev

服务器当前使用stdio MCP传输；通过指向流程将其与MCP客户端集成。

MCP客户端（stdio）设置

因为服务器使用stdio，所以您可以让MCP客户端按需生成它，而不是保留一个长时间运行的守护进程。

  1. 构建一次 npm run build.
  2. （可选但方便）运行 npm link 所以 remote-server-mcp CLI在开发过程中可在全球范围内使用。
  3. 在MCP客户端配置中，定义一个stdio服务器，例如：
[[servers]]
name = "remote-server-mcp"
type = "stdio"
command = "npx"
args = ["-y", "remote-server-mcp@latest"]
startup_timeout_sec = 45

[servers.env]
REMOTE_SERVER_MCP_CONFIG = "/Users/me/.config/remote-server-mcp/config.toml"
REMOTE_SERVER_MCP_LOG_PATH = "/Users/me/.config/remote-server-mcp/server.log"
  • 始终提供 REMOTE_SERVER_MCP_CONFIG；如果没有它，进程将立即退出（客户端参见 Transport closed). REMOTE_SERVER_MCP_LOG_PATH 将遥测技术排除在stdout之外，因此stdio帧保持有效。
  • 如果您尚未发布该包，请指向 command 到 node 并将绝对路径传递给 dist/index.js，或使用 command = "npx", args = ["tsx", "src/index.ts"] 用于实时执行TypeScript。
  • 每次客户端会话启动时，它都会通过MCP日志通道调用二进制流stdout/stderr，并在命令完成时退出——不需要后台服务。

stdio启动故障排除

  • 握手瞬间失败： 确认MCP客户端正在通过这两个 REMOTE_SERVER_MCP_CONFIG 以及（可选） REMOTE_SERVER_MCP_LOG_PATH缺少的配置路径清单为 connection closed: initialize response 因为服务器在发出任何MCP帧之前中止。
  • SSH首次提示执行块： 集 strictHostKeyChecking = false 用于初始连接或预填充 known_hosts 使用远程指纹。通过stdio无法满足交互式“是/否”提示。
  • 后续运行挂起： 多重背景 remote-server-mcp 进程争夺stdio。使用 pgrep -fl remote-server-mcp 并终止陈旧 npm exec … / node … PID，以便MCP客户端可以干净地生成新副本。

测试

npm test

测试涵盖了配置解析、验证失败场景和命令服务编排（包括流式传输和遥测挂钩）。Linting通过以下方式执行：

npm run lint

遥测和挂钩

执行遥测通过Pino发出。默认情况下，日志会转到stderr（因此stdio MCP传输会保持stdout干净）。集 REMOTE_SERVER_MCP_LOG_PATH 将日志写入文件。预/后/错误钩子回调已到位，以供未来的策略执行。

安全注意事项

  • 切勿提交真实凭据或私钥
  • 确保在启用之前填充了主机密钥验证路径 strictHostKeyChecking
  • 在部署到生产环境之前，使用提供的挂钩界面添加确认或白名单

相关 MCP