内容
# exec-vps-mcp
> 用一个很薄的 Python MCP 服务，把 VPS 的任意 root shell 暴露给 Codex、Claude Code 或其他 MCP 客户端。
[给 AI / Agent 的部署与维护说明 → `AGENTS.md`](AGENTS.md)
[脱敏后的实际使用示例 → `docs/real-world-example.md`](docs/real-world-example.md)
[故障排查手册 → `docs/troubleshooting.md`](docs/troubleshooting.md)
## 先说结论
这个项目最核心的能力只有一个：
```text
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。
```text
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：
```python
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，默认地址为：
```text
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()`。
官方资料：
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [MCP Python SDK v2 migration guide](https://py.sdk.modelcontextprotocol.io/migration/)
- [Codex MCP 配置](https://developers.openai.com/codex/mcp)
---
## 2. 你需要什么
```text
一台 Ubuntu / Debian VPS
root 或等价 sudo 权限
Python 3.10+
本地可用的 SSH 公钥登录
支持 Streamable HTTP 的 MCP 客户端
```
不需要 OpenAI API Key。MCP 服务本身不调用模型；它只给已有的 Codex、Claude Code 或其他 Agent 提供工具。
---
## 3. 先由人完成一次 SSH 引导
推荐先让人类完成第一次登录和密钥验证：
```text
人类使用 VPS 初始密码 / 厂商控制台登录
↓
本地生成 SSH 密钥对
↓
只把公钥放入服务器 authorized_keys
↓
确认密钥登录成功
↓
再让 AI / Agent 接手后续部署
```
生成密钥：
```bash
ssh-keygen -t ed25519
```
Linux / macOS：
```bash
ssh-copy-id root@YOUR_SERVER_IP
```
Windows PowerShell：
```powershell
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | ssh root@YOUR_SERVER_IP "umask 077; mkdir -p ~/.ssh; cat >> ~/.ssh/authorized_keys"
```
最后验证：
```bash
ssh root@YOUR_SERVER_IP
```
不要把 SSH 私钥、root 密码或云厂商凭据粘贴到聊天、Issue、日志或公开仓库。在密钥登录验证成功前，不要关闭密码登录。
---
## 4. 安装服务端
以下命令在 VPS 上以 root 执行：
```bash
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 .
```
先运行测试：
```bash
.venv/bin/python -m unittest -v
```
安装 systemd 服务：
```bash
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
```
检查状态：
```bash
systemctl status exec-vps-mcp.service --no-pager
ss -lntp 'sport = :8798'
```
默认应该只看到 `127.0.0.1:8798`，而不是公网地址。
---
## 5. 从本地通过 SSH tunnel 连接
在运行 Codex 的本地电脑上保持下面的 SSH 连接：
```bash
ssh -N -L 8798:127.0.0.1:8798 root@YOUR_SERVER_IP
```
含义是：
```text
本地 127.0.0.1:8798
↓ 加密 SSH tunnel
VPS 127.0.0.1:8798
↓
exec-vps-mcp
```
只要这个 SSH 会话保持运行，本地 MCP 客户端就可以连接：
```text
http://127.0.0.1:8798/mcp
```
如果本地 `8798` 已被占用，可以改成本地其他端口，例如：
```bash
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`](docs/client-setup.md)**
### Codex 快速配置
把 [`examples/codex-config.toml`](examples/codex-config.toml) 中的配置加入 `~/.codex/config.toml`：
```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，执行：
```bash
codex mcp list
```
也可以在 Codex 中使用 `/mcp` 查看连接状态。
其他客户端不要照抄这段 TOML；endpoint 仍然是 `http://127.0.0.1:8798/mcp`，只需换成对应客户端的配置外壳。
---
## 7. 测试工具
先只执行无副作用命令：
```text
请使用 exec_vps 执行：id && pwd && uptime
```
预期结构化结果中的 `exit_code` 为 `0`，`timed_out` 与 `truncated` 为 `false`，`stdout` 应包含：
```text
uid=0(root)
/root
...
```
然后可以尝试只读运维任务：
```text
检查服务器磁盘、内存、负载和失败的 systemd 服务，不要修改任何内容。
```
确认链路正常以后，再决定是否让 Agent 修改服务或配置。
---
## 8. 给 AI 使用时怎么说
普通任务可以直接说目标：
```text
检查 nginx 为什么启动失败，先只读诊断并告诉我原因，不要修改配置。
```
如果允许修改，明确范围：
```text
修复 nginx 配置，但不要修改防火墙、Docker、SSH 和其他服务。修改前备份原文件，完成后运行 nginx -t。
```
涉及删除、覆盖、迁移、数据库、凭据、防火墙和 SSH 时，最好要求 Agent 在执行前停下来说明目标和回滚方法。
仓库中的 [`AGENTS.md`](AGENTS.md) 已经把这些协作规则写给 AI。把仓库交给 Codex、Claude Code 或其他 Agent 时，让它先读该文件。
---
## 9. 同机 Docker 私网接入
如果 MCP 客户端也运行在同一台 VPS 的 Docker 容器中，可以把 systemd 单元改为：
```ini
Environment=MCP_HOST=0.0.0.0
```
客户端连接宿主 Docker bridge gateway，例如：
```text
http://YOUR_BRIDGE_GATEWAY:8798/mcp
```
但必须同时满足：
1. 使用专门的 Docker bridge 网络；
2. 防火墙只允许该 bridge / 子网访问 TCP `8798`；
3. 云厂商安全组和公网防火墙不开放 `8798`；
4. 修改防火墙前先确认 SSH 恢复通道；
5. 从公网实际探测确认 `8798` 不可达。
bridge 名称和子网因机器而异，不要照抄其他机器的地址。先用 `docker network inspect` 查看真实网络，再生成精确规则。
---
## 10. 我实际在用的两条链路
这个仓库来自一套真实运行的个人系统，而不是只在本地跑过的示例。公开文档只保留两条经过脱敏的技术链路：
```text
云端：Telegram / gateway → Codex → vps-admin → Docker 私网 → root MCP
本机：Codex Desktop → 云服务器插件 → 远程 MCP 入口 → exec_vps
```
两条链路最终调用的是同一种能力：服务器上的任意 root shell。区别在于 MCP 客户端在哪里运行，以及怎样抵达服务器。
完整的实际案例、设计取舍、权限边界和验收方法见 [`docs/real-world-example.md`](docs/real-world-example.md)。案例中的服务名、网络名和 MCP key 均为通用占位名。
---
## 11. 日常维护
查看日志：
```bash
journalctl -u exec-vps-mcp.service -n 100 --no-pager
```
更新：
```bash
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
```
停止并禁用：
```bash
systemctl disable --now exec-vps-mcp.service
```
删除前先确认 `/opt/exec-vps-mcp` 里没有你自行加入的配置、备份或数据。本教程不提供自动删除命令，避免 Agent 或人类误删路径。
---
## 12. 常见故障
遇到连接失败、工具不出现、timeout、systemd 启动失败、SSH tunnel 端口冲突或 Docker 私网不可达时，按 [`docs/troubleshooting.md`](docs/troubleshooting.md) 从监听、网络、MCP 初始化、工具调用四层逐步检查。
不要一遇到连接问题就开放公网端口或关闭防火墙。先确认问题发生在哪一层。
---
## 13. 安全边界
公开仓库不要提交或粘贴：
```text
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，也仍可能出现下面的链路：
```text
可信用户
→ Agent 阅读网页 / Issue / repo / email / log / 文档
→ 内容里夹带恶意指令
→ Agent 被诱导调用 exec_vps
→ root
```
认证只能证明“谁能访问 Agent”，不能证明“Agent 读到的内容都是可信指令”。网页、仓库、Issue、日志、邮件、文档和工具输出中的指令都必须视为 untrusted data；只有人类用户明确授权的任务范围可以触发 root 操作。
---
## 14. 项目结构
```text
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 可能造成数据丢失、服务中断、凭据泄露或服务器被接管。
请遵守所在地区法律法规、云服务器厂商政策和相关服务条款。使用者需要自行承担部署和命令执行风险。
连接信息
猜你喜欢
暂无推荐服务器