vm-codex-mcp-bridge
Provides read-only access to explicitly selected project directories on a Linux VM or Linux host, including listing files, reading UTF-8 files up to 256 KiB, and performing bounded case-sensitive literal text searches.
Integrates with OpenAI Codex sessions by exposing read-only tools to list and read explicitly authorized Codex threads via the Codex CLI/App Server, with optional Secure MCP Tunnel support.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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: ServerFS 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 许可证。使用、修改和再分发时请保留版权与许可声明;软件按现状提供,不作担保。维护者发布流程见发布清单。
六个工具
工具 | 用途 |
| 列出允许的项目别名,不返回绝对路径 |
| 列出项目内单层目录 |
| 读取 UTF-8 文件,最大 256 KiB |
| 有界、区分大小写的字面量搜索,返回文件与行号 |
| 列出配置明确授权的会话 ID 与导入别名 |
| 每次读取一个授权会话轮次,或一个已审阅的导入文件 |
没有写文件、执行命令、通用 RPC、恢复会话或开始模型任务的远程工具。App Server 本身可能写日志/状态;这里的“只读”描述桥接公开的业务操作,不是系统级零写入或零网络活动的保证。
快速开始:先只分享项目文件
前提:目标机器是 Linux,已安装 Python 3.11+,当前 Unix 用户有权读取选中的项目。文件功能不需要 Codex CLI、不需要登录 Codex,也不需要任何 API key。
从本仓库下载源码并解压,进入源码根目录
检查代码,把
config.example.json复制为config.json,只替换projects.demo为一个经过审阅的项目绝对路径。保留codex.enabled=false,默认没有任何会话或导入授权校验配置并运行测试:
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 路径。它不能证明项目内容没有秘密,也不能验证某个会话能否读取。
在支持 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。
调用
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。这两个上游组件各自演进,变更后请重新验收。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read-only MCP access to authorized Vocci sessions, notes, files, and memory search.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Read-only MCP server exposing a user ORANO library to their own AI agent.
Read-only MCP server over the developer docs for the portfolio's JSON API, MCP, A2A and NLWeb.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables secure, read-only access to local project files (including text, DOCX, PDF, and XLSX) through MCP, with strict directory whitelisting and no write, edit, or command-execution tools.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to securely list, find, search, read, and stat files in selected Linux directories via read-only MCP tools, with no write, execute, or escape capabilities.6MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to browse selected folders, search filenames, inspect metadata, and read bounded UTF-8 text files through a read-only, token-authenticated interface.1MIT
- AlicenseAqualityCmaintenanceEnables MCP clients to search, read, and record reviewed conclusions from policy-gated allowlisted files, with sanitized chunks and create-only drafts or append-only lessons, without granting general filesystem or execution access. It supports lexical ranking and optional loopback embeddings while rejecting likely credentials and raw challenge flags.5MIT