GrokBot ↔ Hermes Bridge

一个自托管的 MCP 网关和 Agent 插件模板，让 Grok Bot 与您现有的 Hermes Agent 对话。Grok Bot 仍然是聊天界面；Hermes 在您的机器上运行并生成答案。

该仓库与操作者无关：它不包含任何实时端点、令牌、主机名、私有地址、用户路径、账户句柄或对话内容。

快速开始

Linux 或 macOS，一条可审计的命令：

git clone https://github.com/iamsupersocks/grokbot-hermes-bridge.git && cd grokbot-hermes-bridge && ./scripts/install.sh

已克隆：

./scripts/install.sh
python3 scripts/doctor.py

安装程序是本地且可审计的。它不会下载远程 shell，不使用 sudo，不启动网关，除非您传入，否则不会写入真实的公共主机名。提供非交互式和试运行模式供审查和测试：

./scripts/install.sh --dry-run --non-interactive
./scripts/install.sh --non-interactive --endpoint https://mcp.example.com/mcp

然后在 .env.local 中填写剩余的本地路径（权限 600，切勿提交）。所有者代码在磁盘上生成；不要将其粘贴到聊天中。参见 docs/TUTORIAL.md 获取图文教程。当示例主机名或 Hermes 路径仍是占位符时，Doctor 会刻意保持红色。

Related MCP server: lighthouse-mcp-oauth

工作原理

1. 网关在您的 Hermes 安装旁边运行，并恰好暴露两个 MCP 工具：hermes_ask 和 hermes_status。

2. HTTPS 反向代理或隧道使 /mcp 可从 Grok Bot 访问。

3. Grok Bot 发现网关的 OAuth 流程。您在浏览器中使用仅存储在服务器环境中的私有所有者代码批准连接。

4. 插件将用户请求发送给 Hermes 并返回有界回复。

没有 SSH 端点、通用 shell 工具、环境转储或已提交的凭据。所有者代码不会作为 MCP 承载令牌被接受。

要求

• Python 3.11+

• 网关机器上可用的 hermes CLI 和 Hermes 主目录

• 转发到 127.0.0.1:8099 的公共 HTTPS 主机名或隧道

• Grok Bot、Codex、Cursor 或其他支持 OAuth 的 Streamable HTTP MCP 客户端

运行网关

在安装程序（或等效的本地 venv + .env.local 设置）之后：

. .venv/bin/activate
set -a
. ./.env.local
set +a
python -m hermes_gateway.mcp --host 127.0.0.1 --port 8099

.env.local 至少必须包含：

HERMES_BRIDGE_SECRET=<64-random-hex-characters>
HERMES_BRIDGE_PUBLIC_BASE_URL=https://mcp.example.com
HERMES_BRIDGE_ALLOWED_HOSTS=localhost,127.0.0.1,mcp.example.com
HERMES_BRIDGE_HERMES_BIN=/absolute/path/to/hermes
HERMES_BRIDGE_HERMES_HOME=/absolute/path/to/hermes-home

GET /health 应返回 {"status":"ok"}。在服务前面放置 HTTPS；不要直接暴露 8099 端口。参见 deploy/ 获取通用示例。

配置插件

安装程序会为您调用 scripts/configure_plugin.py。要重复执行：

python scripts/configure_plugin.py https://mcp.example.com/mcp

生成的配置仅包含 URL。不要添加 Authorization 标头：Grok Bot 使用 OAuth 发现和 PKCE 获取自己的访问令牌。

将此文件夹安装或打包为插件，重启 Grok Bot，然后启用连接器。首次连接会打开批准页面。输入存储在 HERMES_BRIDGE_SECRET 中的相同所有者代码。

在此桥接旁边添加 Composio

Corey Ganim 的 Grok Bot 技巧 使用 Composio Connect 来超越客户端的原生连接器目录。Composio 将 Connect 描述为一个托管 MCP 端点，通过 7 个元工具支持 1000+ 应用。它并非字面意义上的每个 MCP 服务器，也不随此仓库捆绑。

保持两个连接相互独立：

此处的 .grok-plugin、.cursor-plugin 和 .codex-plugin 清单仅安装 Hermes 桥接。Composio 流量不经过 Hermes，Composio 也不会取代此桥接。参见教程了解完整的设置模型和安全边界。

Grok Bot 的可见消息限制

Grok Bot 目前会在每次工具调用前发出一条简短的可见消息，例如"我将把它传递给 Hermes。"插件无法隐藏或移除该主机级步骤。捆绑的技能使其保持简短，并防止 Grok Bot 冒充 Hermes。

安全模型

• 固定的 Hermes 可执行文件；无 shell 调用

• 有界的提示、输出、轮次、超时、负载、速率和并发

• 最小的子进程环境

• OAuth 发现、动态客户端注册、授权码 + PKCE、签名访问令牌和刷新令牌

• 需要所有者批准；所有者代码永远不会作为承载令牌工作

• 主机/来源检查、DNS 重绑定保护、仅 localhost 绑定、日志编辑和过滤的状态输出

• 如果端点、所有者代码、Hermes 二进制文件或 Hermes 主目录无效，则启动时故障关闭

OAuth 提供程序有意设计为单所有者。已注册的客户端在本地以 mode-0600 JSON 文件持久化；待处理的批准和授权码保存在内存中。轮换 HERMES_BRIDGE_SECRET 会使已颁发的令牌失效。

测试与审计

python -m pip install -e '.[dev]'
python -m unittest discover -s tests -v
python src/privacy_scan.py --root .
python scripts/audit_git_history.py
python3 scripts/doctor.py

在暴露端点之前，还请阅读 SECURITY.md。此仓库以全新的公共 Git 历史开始；它不继承私有实现历史。

许可证

MIT。参见 LICENSE。