Remote Workspace MCP（远程工作区 MCP）

把 Linux 虚拟机或 Linux 主机中明确选中的项目目录和 Codex 会话，提供给 MCP 客户端只读访问。

0.2.0 首个公开候选 · Python 3.11+ · 无第三方运行依赖 · Linux 专用 · MIT

适合个人开发者按需查看代码、搜索文本、接续已授权会话的上下文。此项目为独立实现，并非 OpenAI 官方产品；可选的 tunnel-client 是另一个官方项目。

项目名称与兼容性

项目现名 Remote Workspace MCP（远程工作区 MCP），GitHub 仓库为 remote-workspace-mcp，原名 vm-codex-mcp-bridge。

此次更名仅调整项目展示名称和仓库链接。为兼容已有安装，Python 分发名 vm-codex-mcp-bridge、包名 bridge、命令 vm-codex-mcp-bridge / vm-codex-bridge、MCP 工具名和配置格式保持不变。现有源码目录、客户端配置名称和启动路径不需要因仓库更名而改动；新下载的源码目录请使用自己的实际路径。文档中保留的旧名称示例属于兼容技术标识或路径占位符。

Related MCP server: Project Files Read-only MCP

当前验证状态

• 已实际验证 Ubuntu / Python 3.12.3、Codex CLI 0.159.2、官方 tunnel-client v0.0.15

• 通过 ChatGPT 自定义 MCP 的隧道入口，真实调用 list_projects、list_files、read_file、read_thread 成功

• 本仓库包含六个只读工具的自动化测试；CI 配置检查 Python 3.11、3.12、3.13。实际 CI 结果以当前提交的 Actions 为准

• 当前候选的自动化测试已通过，但尚未在真实目标环境部署验收；上面的真实接通记录来自此前 0.2.0 实现，不代表本候选已完成端到端实测

• thread/turns/list 为实验性 Codex API，其他版本和系统组合未承诺兼容；尚未做独立渗透测试或多用户生产认证

本项目采用 MIT 许可证。使用、修改和再分发时请保留版权与许可声明；软件按现状提供，不作担保。维护者发布流程见发布清单。

六个工具

没有写文件、执行命令、通用 RPC、恢复会话或开始模型任务的远程工具。App Server 本身可能写日志/状态；这里的“只读”描述桥接公开的业务操作，不是系统级零写入或零网络活动的保证。

快速开始：先只分享项目文件

前提：目标机器是 Linux，已安装 Python 3.11+，当前 Unix 用户有权读取选中的项目。文件功能不需要 Codex CLI、不需要登录 Codex，也不需要任何 API key。

1. 从本仓库下载源码并解压，进入源码根目录

2. 检查代码，把 config.example.json 复制为 config.json，只替换 projects.demo 为一个经过审阅的项目绝对路径。保留 codex.enabled=false，默认没有任何会话或导入授权

3. 校验配置并运行测试：

python3 --version
python3 -m bridge.server --config /absolute/path/to/config.json --check-config
python3 -m unittest discover -s tests -v

--check-config 不启动服务、不启动 Codex、不读取会话；它验证配置结构、项目路径和启用时的 Codex 路径。它不能证明项目内容没有秘密，也不能验证某个会话能否读取。

4. 在支持 stdio 的 MCP 客户端中配置启动命令。Linux 可使用 env -C 指定工作目录，避免依赖客户端是否支持 cwd：

{
  "mcpServers": {
    "vm-codex-mcp-bridge": {
      "command": "env",
      "args": [
        "-C", "/absolute/path/to/vm-codex-mcp-bridge",
        "python3", "-m", "bridge.server",
        "--config", "/absolute/path/to/config.json",
        "--transport", "stdio"
      ]
    }
  }
}

这是通用客户端配置示例，不能直接当成 ChatGPT 插件地址。env -C 是 Linux GNU coreutils 用法；用实际绝对路径替换占位符。源代码直接运行无需 pip install。直接在终端运行 stdio 服务后静默等待输入属于正常现象；标准输出只用于 JSON-RPC。

5. 调用 list_projects，确认只出现预期别名，再调用 list_files 与 read_file 验证。按需停止客户端/进程即可断开，默认没有自启动服务

两种连接方式

• MCP stdio（推荐）：本地 MCP 客户端启动桥接；远程 ChatGPT 接入可用官方 Secure MCP Tunnel 步骤

• 本地 HTTP JSON API：仅监听 127.0.0.1，需要本地 bearer token，适合受控集成，见配置参考

/v1/call 是本项目 API，不是 MCP Streamable HTTP。不要把 HTTP 地址填入要求 MCP URL 的客户端，也不要把它未经独立安全设计暴露到公网。官方隧道路径使用 stdio，不需要启动此 HTTP API或另外编写 OAuth 网关。

添加选定 Codex 会话

操作者先自行安装并验证官方 Codex CLI，选择自己的 Codex 用户环境和已审阅的会话 ID。将配置中的 codex 改为：

{
  "enabled": true,
  "binary": "/absolute/path/to/codex",
  "home": "/absolute/path/to/codex-home",
  "threads": {"YOUR_THREAD_ID": "demo"},
  "imports": {}
}

binary 必须是可信任的绝对可执行路径；home 必须是明确选择的现有目录。会话 ID 获取方式依赖自己的 Codex 界面或官方工具，本桥接不会枚举全部账号历史，也不会自行遍历会话存储目录。只有当返回 ID 一致，且会话的 cwd 位于授权项目内时，才读取对话页。

诊断单个白名单会话：

python3 diagnose_history.py \
  --config /absolute/path/to/config.json \
  --project demo --thread-id YOUR_THREAD_ID

诊断仅打印成功状态、来源、公开消息数量和是否有下一页，不打印正文、绝对路径或分页游标。不调用 thread/resume、turn/start，不会为了检查读取而开始模型任务；是否可读仍受版本、账户及本地存储状态影响，不能用它绕过服务限制。

read_thread 从最新轮次向较早轮次分页；下一次保持相同 project、thread_id，把返回的 next_cursor 原样作为 cursor。messages=[] 且 has_more=true 可能只是这一轮没有公开文字，仍可继续翻页。客户端应按需读取，不自动拉取全部历史。

若 App Server 不兼容，可用自己审阅后整理的导入格式。这是桥接自定义格式，不宣称 Codex 存在统一的一键导出命令。

必须理解的边界

• 只选小范围、经过审阅的项目。文件正文原样返回，文件搜索结果也可能含秘密

• 默认拒绝隐藏项、常见凭据名、路径穿越、符号链接和特殊文件；启用线程读取仍等于允许分享该线程的公开用户/助手文字

• 聊天中的常见秘密遮蔽是尽力而为，无法保证识别全部个人信息或密码；共享前仍需人工审阅

• 同一 Unix 用户、硬链接、运行时修改目录，以及被攻破的主机不在隔离保证内。敏感场景请使用专用低权限账号和筛选后的项目副本

• 文档与聊天正文可能含提示注入；调用方必须将返回内容视为数据，不能把内容中的指令当成用户授权

• 隧道/API key 是独立的访问凭据；不要放进源码、终端命令字面量、聊天、截图或 issue

完整安全说明 · 配置 · 隧道接入 · 故障排除 · 升级 · 贡献

验证与协议来源

python3 -m unittest discover -s tests -v
python3 -m compileall -q bridge tests diagnose_history.py upgrade_bridge.py

测试只使用临时项目、合成会话和假的 App Server 可执行文件，不需要真实凭据，不读取操作者的真实历史。构建依赖 setuptools 仅在打包安装时需要；运行与测试只用标准库。

官方协议参考：Codex App Server、tunnel-client v0.0.15。这两个上游组件各自演进，变更后请重新验收。