How do I install Exec Vps?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Exec Vps need an API key?

No required environment variable is listed on this record.

What transport does Exec Vps use?

Exec Vps runs locally over stdio.

When was Exec Vps last checked?

Last checked 2026-10-27. A detailed tutorial and minimal MCP server that gives AI agents an unrestricted VPS root shell.

Servidor MCP Exec Vps

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 可能造成数据丢失、服务中断、凭据泄露或服务器被接管。

请遵守所在地区法律法规、云服务器厂商政策和相关服务条款。使用者需要自行承担部署和命令执行风险。

Exec Vps

Añadir este servidor

Host a copy with our keys and logs.

Server facts

Tools

Questions