yding-git/exec-vps-mcp

A detailed tutorial and minimal MCP server that gives AI agents an unrestricted VPS root shell.

About exec-vps-mcp

用一个很薄的 Python MCP 服务，把 VPS 的任意 root shell 暴露给 Codex、Claude Code 或其他 MCP 客户端。

它收到一段 shell 命令，在 VPS 上以 root 身份执行，再把退出码、stdout、stderr、超时和截断状态作为结构化结果返回给 AI。

这很方便，也非常危险。连接到这个 MCP 的 AI 理论上可以读取服务器文件、修改服务、操作 Docker、防火墙和数据库，也可以执行删除或关机命令。只有在你完全控制客户端、网络入口和服务器时才应使用。

本仓库不会把 8798 直接开放到公网。默认只监听 127.0.0.1，推荐通过 SSH tunnel 使用；同机 Docker 场景可以改为私有 bridge 网络，但仍应由防火墙阻止公网访问。

服务端使用官方 MCP Python SDK v2 的 MCPServer。返回类型使用 TypedDict，SDK 会据此生成并校验结构化 output schema：

@mcp.tool() 根据 Python 类型和 docstring 自动生成工具定义；mcp.run(transport="streamable-http") 通过 HTTP 提供 MCP endpoint，默认地址为：

stdout 和 stderr 分别最多返回 1 MiB；任一路超过上限时只返回前 1 MiB，并把 truncated 设为 true。子进程输出先写入临时文件，避免把无限输出全部保存在 Python 内存或 MCP response 中。

本项目使用 MCP Python SDK v2 稳定线并约束为 mcp=2,<3，使用 MCPServer API；HTTP 的 host / port 参数传给 run()。

- MCP Python SDK - MCP Python SDK v2 migration guide - Codex MCP 配置

不需要 OpenAI API Key。MCP 服务本身不调用模型；它只给已有的 Codex、Claude Code 或其他 Agent 提供工具。

不要把 SSH 私钥、root 密码或云厂商凭据粘贴到聊天、Issue、日志或公开仓库。在密钥登录验证成功前，不要关闭密码登录。

然后把客户端 URL 攡成 http://127.0.0.1:18798/mcp。

这个服务使用标准 Streamable HTTP MCP。Codex、Claude Code 和 OpenCode 都能原生连接同一个 endpoint；Pi 核心不内置 MCP，需要经过审查的扩展。

协议可以通用，客户端配置文件不能强行通用：Codex 使用 TOML，Claude Code 使用 CLI 或 .mcp.json，OpenCode 使用 opencode.json。完整换算方法、可复制配置和 Pi 的人工操作说明见：

Codex / Claude Code / OpenCode / Pi 客户端配置教程 → docs/client-setup.md

把 examples/codex-config.toml 中的配置加入 ~/.codex/config.toml：

其他客户端不要照抄这段 TOML；endpoint 仍然是 http://127.0.0.1:8798/mcp，只需换成对应客户端的配置外壳。

From the project README.

Maintaining this server?

Add the radar badge to your README — it shows your project was picked up by MCP Radar and links to this page:

[![On MCP Radar](https://mcp.liqiwa.com/badge.svg)](https://mcp.liqiwa.com/s/yding-git--exec-vps-mcp.html)

Related MCP servers