exec-vps-mcp
用一个很薄的 Python MCP 服务，把 VPS 的任意 root shell 暴露给 Codex、Claude Code 或其他 MCP 客户端。
给 AI / Agent 的部署与维护说明 → AGENTS.md
脱敏后的实际使用示例 → docs/real-world-example.md
故障排查手册 → docs/troubleshooting.md
先说结论
这个项目最核心的能力只有一个：
exec_vps(command: string, timeout?: number) →
{
exit_code: integer | null,
stdout: string,
stderr: string,
timed_out: boolean,
truncated: boolean
}
它收到一段 shell 命令，在 VPS 上以 root 身份执行，再把退出码、stdout、stderr、超时和截断状态作为结构化结果返回给 AI。
Codex / Claude Code / Agent
↓ MCP Streamable HTTP
exec-vps-mcp
↓ subprocess.Popen(..., shell=True)
VPS root shell
这很方便，也非常危险。连接到这个 MCP 的 AI 理论上可以读取服务器文件、修改服务、操作 Docker、防火墙和数据库，也可以执行删除或关机命令。只有在你完全控制客户端、网络入口和服务器时才应使用。
本仓库不会把 8798 直接开放到公网。默认只监听 127.0.0.1，推荐通过 SSH tunnel 使用；同机 Docker 场景可以改为私有 bridge 网络，但仍应由防火墙阻止公网访问。
1. 它是怎么做出来的
服务端使用官方 MCP Python SDK v2 的 MCPServer。返回类型使用 TypedDict，SDK 会据此生成并校验结构化 output schema：
class ExecResult(TypedDict):
exit_code: int | None
stdout: str
stderr: str
timed_out: bool
truncated: bool
@mcp.tool()
def exec_vps(command: str, timeout: int = 30) -> ExecResult:
with tempfile.TemporaryFile() as stdout_file, tempfile.TemporaryFile() as stderr_file:
process = subprocess.Popen(
command,
shell=True,
stdout=stdout_file,
stderr=stderr_file,
cwd="/root",
)
process.wait(timeout=min(timeout, 120))
return {"exit_code": process.returncode, ...}
@mcp.tool() 根据 Python 类型和 docstring 自动生成工具定义；mcp.run(transport="streamable-http") 通过 HTTP 提供 MCP endpoint，默认地址为：
http://127.0.0.1:8798/mcp
stdout 和 stderr 分别最多返回 1 MiB；任一路超过上限时只返回前 1 MiB，并把 truncated 设为 true。子进程输出先写入临时文件，避免把无限输出全部保存在 Python 内存或 MCP response 中。
本项目使用 MCP Python SDK v2 稳定线并约束为 mcp>=2,<3，使用 MCPServer API；HTTP 的 host / port 参数传给 run()。
官方资料：
2. 你需要什么
一台 Ubuntu / Debian VPS
root 或等价 sudo 权限
Python 3.10+
本地可用的 SSH 公钥登录
支持 Streamable HTTP 的 MCP 客户端
不需要 OpenAI API Key。MCP 服务本身不调用模型；它只给已有的 Codex、Claude Code 或其他 Agent 提供工具。
3. 先由人完成一次 SSH 引导
推荐先让人类完成第一次登录和密钥验证：
人类使用 VPS 初始密码 / 厂商控制台登录
↓
本地生成 SSH 密钥对
↓
只把公钥放入服务器 authorized_keys
↓
确认密钥登录成功
↓
再让 AI / Agent 接手后续部署
生成密钥：
ssh-keygen -t ed25519
Linux / macOS：
ssh-copy-id root@YOUR_SERVER_IP
Windows PowerShell：
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | ssh root@YOUR_SERVER_IP "umask 077; mkdir -p ~/.ssh; cat >> ~/.ssh/authorized_keys"
最后验证：
ssh root@YOUR_SERVER_IP
不要把 SSH 私钥、root 密码或云厂商凭据粘贴到聊天、Issue、日志或公开仓库。在密钥登录验证成功前，不要关闭密码登录。
4. 安装服务端
以下命令在 VPS 上以 root 执行：
apt-get update
apt-get install -y git python3 python3-venv
git clone https://github.com/yding-git/exec-vps-mcp.git /opt/exec-vps-mcp
cd /opt/exec-vps-mcp
python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install .
先运行测试：
.venv/bin/python -m unittest -v
安装 systemd 服务：
install -m 0644 deploy/exec-vps-mcp.service /etc/systemd/system/exec-vps-mcp.service
systemctl daemon-reload
systemctl enable --now exec-vps-mcp.service
检查状态：
systemctl status exec-vps-mcp.service --no-pager
ss -lntp 'sport = :8798'
默认应该只看到 127.0.0.1:8798，而不是公网地址。
5. 从本地通过 SSH tunnel 连接
在运行 Codex 的本地电脑上保持下面的 SSH 连接：
ssh -N -L 8798:127.0.0.1:8798 root@YOUR_SERVER_IP
含义是：
本地 127.0.0.1:8798
↓ 加密 SSH tunnel
VPS 127.0.0.1:8798
↓
exec-vps-mcp
只要这个 SSH 会话保持运行，本地 MCP 客户端就可以连接：
http://127.0.0.1:8798/mcp
如果本地 8798 已被占用，可以改成本地其他端口，例如：
ssh -N -L 18798:127.0.0.1:8798 root@YOUR_SERVER_IP
然后把客户端 URL 攡成 http://127.0.0.1:18798/mcp。
6. 连接 Agent 客户端
这个服务使用标准 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
Codex 快速配置
把 examples/codex-config.toml 中的配置加入 ~/.codex/config.toml：
[mcp_servers.exec-vps]
url = "http://127.0.0.1:8798/mcp"
enabled = true
required = true
enabled_tools = ["exec_vps"]
tool_timeout_sec = 130
然后重新启动 Codex，执行：
codex mcp list
也可以在 Codex 中使用 /mcp 查看连接状态。
其他客户端不要照抄这段 TOML；endpoint 仍然是 http://127.0.0.1:8798/mcp，只需换成对应客户端的配置外壳。
7. 测试工具
先只执行无副作用命令：
请使用 exec_vps 执行：id && pwd && uptime
预期结构化结果中的 exit_code 为 0，timed_out 与 truncated 为 false，stdout 应包含：
uid=0(root)
/root
...
然后可以尝试只读运维任务：
检查服务器磁盘、内存、负载和失败的 systemd 服务，不要修改任何内容。
确认链路正常以后，再决定是否让 Agent 修改服务或配置。
8. 给 AI 使用时怎么说
普通任务可以直接说目标：
检查 nginx 为什么启动失败，先只读诊断并告诉我原因，不要修改配置。
如果允许修改，明确范围：
修复 nginx 配置，但不要修改防火墙、Docker、SSH 和其他服务。修改前备份原文件，完成后运行 nginx -t。
涉及删除、覆盖、迁移、数据库、凭据、防火墙和 SSH 时，最好要求 Agent 在执行前停下来说明目标和回滚方法。
仓库中的 AGENTS.md 已经把这些协作规则写给 AI。把仓库交给 Codex、Claude Code 或其他 Agent 时，让它先读该文件。
9. 同机 Docker 私网接入
如果 MCP 客户端也运行在同一台 VPS 的 Docker 容器中，可以把 systemd 单元改为：
Environment=MCP_HOST=0.0.0.0
客户端连接宿主 Docker bridge gateway，例如：
http://YOUR_BRIDGE_GATEWAY:8798/mcp
但必须同时满足：
- 使用专门的 Docker bridge 网络；
- 防火墙只允许该 bridge / 子网访问 TCP
8798； - 云厂商安全组和公网防火墙不开放
8798； - 修改防火墙前先确认 SSH 恢复通道；
- 从公网实际探测确认
8798不可达。
bridge 名称和子网因机器而异，不要照抄其他机器的地址。先用 docker network inspect 查看真实网络，再生成精确规则。
10. 我实际在用的两条链路
这个仓库来自一套真实运行的个人系统，而不是只在本地跑过的示例。公开文档只保留两条经过脱敏的技术链路：
云端：Telegram / gateway → Codex → vps-admin → Docker 私网 → root MCP
本机：Codex Desktop → 云服务器插件 → 远程 MCP 入口 → exec_vps
两条链路最终调用的是同一种能力：服务器上的任意 root shell。区别在于 MCP 客户端在哪里运行，以及怎样抵达服务器。
完整的实际案例、设计取舍、权限边界和验收方法见 docs/real-world-example.md。案例中的服务名、网络名和 MCP key 均为通用占位名。
11. 日常维护
查看日志：
journalctl -u exec-vps-mcp.service -n 100 --no-pager
更新：
cd /opt/exec-vps-mcp
git pull --ff-only
.venv/bin/pip install .
.venv/bin/python -m unittest -v
systemctl restart exec-vps-mcp.service
systemctl status exec-vps-mcp.service --no-pager
停止并禁用：
systemctl disable --now exec-vps-mcp.service
删除前先确认 /opt/exec-vps-mcp 里没有你自行加入的配置、备份或数据。本教程不提供自动删除命令，避免 Agent 或人类误删路径。
12. 常见故障
遇到连接失败、工具不出现、timeout、systemd 启动失败、SSH tunnel 端口冲突或 Docker 私网不可达时，按 docs/troubleshooting.md 从监听、网络、MCP 初始化、工具调用四层逐步检查。
不要一遇到连接问题就开放公网端口或关闭防火墙。先确认问题发生在哪一层。
13. 安全边界
公开仓库不要提交或粘贴：
SSH 私钥
root / VPS 密码
云厂商 API Key
Bot Token
OAuth Token
Cookie
生产 MCP URL 中的凭据
真实服务器 IP（如果你不希望公开）
包含秘密的 systemd EnvironmentFile
还要知道：
shell=True会让 shell 解释整段命令；这正是任意 shell 能力的来源。- systemd 使用
User=root，所以工具调用拥有完整宿主权限。 timeout只限制 MCP 调用等待多久，并在超时后终止直接启动的 shell；它不是 sandbox、资源限制或完整的 process-tree containment。fork、后台运行或 daemonize 的后代进程可能继续存在。长期任务应交给 systemd、tmux 或容器运行时等 supervisor。- stdout 和 stderr 的 1 MiB 上限只限制返回内容与 Python 内存，不限制命令自身的 CPU、磁盘、网络或进程资源消耗。
- MCP 服务自身没有认证；安全依赖回环地址、SSH tunnel 或严格私网边界。
- Agent 的文字规则不是操作系统权限隔离，也不能替代备份和恢复通道。
- 不要把这个 endpoint 直接暴露到公网。
间接提示注入也是 root 风险
即使只有可信用户能访问 Agent，也仍可能出现下面的链路：
可信用户
→ Agent 阅读网页 / Issue / repo / email / log / 文档
→ 内容里夹带恶意指令
→ Agent 被诱导调用 exec_vps
→ root
认证只能证明“谁能访问 Agent”，不能证明“Agent 读到的内容都是可信指令”。网页、仓库、Issue、日志、邮件、文档和工具输出中的指令都必须视为 untrusted data；只有人类用户明确授权的任务范围可以触发 root 操作。
14. 项目结构
exec-vps-mcp/
├── README.md
├── AGENTS.md
├── LICENSE
├── pyproject.toml
├── server.py
├── test_server.py
├── deploy/
│ └── exec-vps-mcp.service
├── examples/
│ ├── codex-config.toml
│ ├── claude-code.mcp.json
│ └── opencode.json
└── docs/
├── client-setup.md
├── real-world-example.md
└── troubleshooting.md
Disclaimer
这个项目用于你自己控制的服务器、个人运维、学习和开发测试。任意 root shell 可能造成数据丢失、服务中断、凭据泄露或服务器被接管。
请遵守所在地区法律法规、云服务器厂商政策和相关服务条款。使用者需要自行承担部署和命令执行风险。
