Haru VPS MCP

为 ChatGPT 打造的通往迷你电脑的迷你隧道。

Haru VPS MCP 是一个小型的自托管 MCP 网关，用于隔离的 VPS 工作区。它为 MCP 客户端提供一组有限的文件系统和 shell 功能，而不会让主机本身成为工作区。

MCP client / authenticated tunnel
              |
              v
      Haru MCP gateway
        127.0.0.1:8765
              |
       +------+------+
       |             |
       v             v
 filesystem MCP   shell MCP
  loopback only   loopback only
       |             |
       +------v------+
       isolated workspace

公共/私有边界

本仓库是一个干净的公共参考分发版，并非作者私有生产环境的镜像。它有意排除了私有域名、机器身份、凭据、事件证据、生产部署状态、相邻的个人服务以及特定于所有者的工作区内容。

可复用的边界很简单：网关和委托的工作区后端保持在回环上，而任何远程访问都由单独认证的隧道或反向代理提供。

Related MCP server: FieldCure MCP Filesystem Server

安全模型

Haru MCP 公开了强大的工作区文件系统和 shell 工具，因此请将该端点视为特权端点。

• 网关拒绝非回环绑定地址。

• 工作区后端 URL 必须是显式的回环 HTTP 端点，且不能包含凭据。

• 可选的公共 Host/Origin 允许列表仅用于传输加固。它们不是身份验证。

• deploy/Caddyfile.example 默认以 HTTP 403 拒绝访问。仅当您的入口层确实对客户端进行身份验证时，才替换它。

• 请勿在互联网上匿名暴露网关或工作区后端。

• 保持委托的工作区为可丢弃的，并与主机配置、凭据、主目录和生产数据分离。

首次公开提取是一个参考实现。它保留了私有项目中的保守边界，但并不意味着未经操作员审查的任意部署都是生产安全的。

安装和测试

需要 Python 3.10 或更高版本。

python -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
pytest

您还可以运行仓库本地的验证入口点：

./deploy/verify.sh

配置

从示例环境文件开始：

cp deploy/haru-mcp.env.example .env

默认情况下，网关监听 127.0.0.1:8765/mcp，并委托给端口 8766 上的两个回环 MCP 后端端点。这些后端本身应限定在专用工作区根目录内。

如果经过身份验证的反向代理或隧道将公共主机名转发到回环网关，请同时设置以下两项：

HARU_MCP_PUBLIC_HOST=mcp.example.com
HARU_MCP_PUBLIC_ORIGIN=https://mcp.example.com

这些设置仅扩展 Host/Origin 验证。它们不会添加身份验证。

运行

haru-mcp

公共工具面故意保持很小：网关健康检查、工作区目录列表/读取/写入/编辑/移动/stat，以及委托给回环 MCP 后端的隔离 shell 执行。

部署示例

deploy/haru-mcp.service.example 展示了一个加固的 systemd 服务形态。deploy/Caddyfile.example 在操作员提供经过身份验证的入口设计之前，有意保持默认拒绝状态。

许可证

该公共仓库尚未选择许可证。许可将作为所有者在更广泛发布之前的后续事项。