chatgpt-mcp

一个无状态的 MCP 服务器，将 Linux 计算机上显式配置的能力暴露给 ChatGPT 或任何兼容的 MCP 客户端。

ChatGPT / MCP client
        |
        | MCP 2026-07-28
        v
chatgpt-mcp
        |
        | typed ComputerAdapter seam
        v
local operating system

ChatGPT 选择要调用哪个工具。chatgpt-mcp 会根据本地能力配置验证调用并执行操作。它是一个轻量协议适配器，而不是第二个规划器，也不会添加自己的交互式审批循环。

架构：SPEC.md。交付历史：PLAN.md。详细的 ChatGPT/隧道指南：docs/CHATGPT.md。

能力

除 system.info 外，每个能力族都是选择加入的。在可行的情况下，被禁用的能力族会从 MCP 工具发现中省略。

要求

核心服务器：

• Linux

• Node.js 22+

• pnpm 11.20.0（安装程序通过 Corepack 或 npx 获取固定版本）

• 由 ./install.sh 安装的持久隧道的 systemd 用户服务

可选的主机命令取决于你启用的内容：

• 服务：systemctl

• 打开浏览器：xdg-open

• 桌面输入：xdotool

• 截图：grim、gnome-screenshot、scrot 或 ImageMagick import 之一

快速安装程序可以在缺少时安装当前官方 OpenAI tunnel-client 和常见的 Debian/Ubuntu 桌面辅助工具。

快速安装：ChatGPT + 你的 Linux 计算机

对于单台计算机，推荐路径是：

ChatGPT Developer Mode
        |
OpenAI Secure MCP Tunnel
        |
        | outbound HTTPS
        v
tunnel-client on your computer
        |
        | stdio
        v
chatgpt-mcp

无需公共入站监听器。

快速安装程序有意使用 config.full.example.json，它授予由所有者控制的广泛访问权限：从 / 进行文件系统读写、通配符可执行文件访问、进程/服务控制、打开浏览器、截图以及受支持的桌面输入。如果你想要更窄的权限，请改用 config.example.json 和手动设置。

1. 创建 OpenAI MCP 隧道

打开：

https://platform.openai.com/settings/organization/tunnels

创建一个隧道并复制其 ID。它看起来像：

tunnel_0123456789abcdef0123456789abcdef

对于 ChatGPT 使用，请将隧道关联到应能看到它的 ChatGPT 工作区/账户。

当前权限划分：

• 创建/编辑/删除隧道：Tunnels Read + Manage

• 运行 tunnel-client 或在 ChatGPT 中选择隧道：Tunnels Read + Use

2. 创建运行时 API 密钥

打开：

https://platform.openai.com/settings/organization/api-keys

创建一个普通的运行时 API 密钥。不要为长期运行的隧道守护进程使用管理员 API 密钥。

安装程序会以隐藏的终端输入方式询问生成的 sk-... 值，并将其以受限权限本地存储在 .secrets/runtime-api-key 中。

为什么隧道需要 API 密钥？

该密钥用于向 OpenAI 的隧道控制平面认证 tunnel-client。它证明本地守护进程被允许使用所选隧道。

chatgpt-mcp 不会使用它来调用 OpenAI 模型 API。在此设置中，ChatGPT 已经是模型/客户端；Secure MCP Tunnel 只是让该 ChatGPT 对话到达本地 MCP 服务器的私有传输通道。

tunnel_...   = which tunnel this computer belongs to
sk-...       = permission for tunnel-client to use that tunnel

chatgpt-mcp 不会使用此运行时密钥发起 /v1/responses 或其他模型推理请求。OpenAI API 模型计费与 ChatGPT 订阅使用是分开的。当前的 Secure MCP Tunnel 文档没有发布单独的隧道定价方案；如果情况有变，请查看最新的 OpenAI 文档。

3. 克隆并运行安装程序

git clone https://github.com/alexcodeplace/chatgpt-mcp.git
cd chatgpt-mcp
./install.sh

安装程序会：

• 如果尚未提供隧道 ID 和运行时 API 密钥，则进行询问；

• 将这两个值保护在 .secrets/ 下；

• 获取项目固定的 pnpm 11.20.0，无需可写的 /usr/bin Corepack 垫片；

• 安装依赖并运行完整的项目门禁；

• 从广泛控制模板创建 config.local.json；

• 在受支持的 Linux 架构上，如果缺少官方 OpenAI tunnel-client，则进行安装；

• 在 Debian/Ubuntu 上按需安装常见的桌面辅助工具；

• 初始化 chatgpt-computer 隧道配置文件；

• 使用临时的回环健康检查端口，以便 8080 端口上的现有服务不会阻塞安装；

• 运行 tunnel-client doctor --explain；

• 安装并启动 ~/.config/systemd/user/chatgpt-mcp-tunnel.service；

• 验证服务和隧道诊断。

也支持非交互式设置：

export CONTROL_PLANE_TUNNEL_ID='tunnel_0123456789abcdef0123456789abcdef'
export CONTROL_PLANE_API_KEY='sk-...'
./install.sh --yes

不要将 API 密钥直接放在 ./install.sh ... 命令行上，也不要将其提交到 Git。

要跳过可选的桌面软件包安装：

./install.sh --no-desktop

4. 将其添加到 ChatGPT

在隧道服务运行时：

1. 在 ChatGPT 网页中，打开 Settings → Security and login → Developer mode 并启用它。

2. 打开 https://chatgpt.com/plugins。

3. 选择加号按钮并创建一个开发者模式应用。

4. 在 Connection 下，选择 Tunnel。

5. 选择你创建的隧道，或在提示时粘贴其 tunnel_id。

6. 在对话中启用新应用。

7. 首次测试：Use my computer MCP's system.info tool and report the hostname and enabled capabilities.

如果隧道未列出，请验证其 ChatGPT 工作区关联以及 Tunnels Read + Use 权限。

状态与卸载

./scripts/tunnel-status.sh

状态命令会自行加载已保存的运行时密钥，并使用临时的健康检查监听器，因此你无需手动导出 CONTROL_PLANE_API_KEY 即可运行诊断。

在保留本地配置/机密不变的情况下移除持久用户服务：

./scripts/tunnel-uninstall.sh

手动安装 / 开发

仓库固定使用 pnpm 11.20.0。Corepack 无需 corepack enable 即可强制使用该确切版本：

git clone https://github.com/alexcodeplace/chatgpt-mcp.git
cd chatgpt-mcp
corepack pnpm@11.20.0 install
corepack pnpm@11.20.0 gate

pnpm gate 运行类型检查、行为测试和 TypeScript 构建。

如果 Corepack 不可用，请改用 npx -y pnpm@11.20.0。

手动配置

cp config.example.json config.local.json
export CHATGPT_MCP_CONFIG="$PWD/config.local.json"

默认配置仅暴露 system.info。有关每个能力族，请参阅 config.example.json。config.local.json 和 .secrets/ 已被 gitignore 忽略。

如果要有意授予广泛的权限，请改为复制 config.full.example.json。

通过 stdio 启动

corepack pnpm@11.20.0 build
CHATGPT_MCP_CONFIG="$PWD/config.local.json" node dist/src/stdio.js

stdout 保留用于 MCP 协议流量。诊断信息输出到 stderr。

通过 HTTP 启动

corepack pnpm@11.20.0 build
CHATGPT_MCP_CONFIG="$PWD/config.local.json" corepack pnpm@11.20.0 start:http

默认端点：

http://127.0.0.1:3210/mcp

健康检查：

curl http://127.0.0.1:3210/healthz

HTTP 保持无状态。除非显式配置了允许的主机，否则拒绝非回环绑定。

信任边界

• 文件系统操作通过集中的路径授权，该授权会拒绝路径遍历、同级前缀技巧和符号链接逃逸。

• shell.exec 使用直接的可执行文件 + 参数数组启动方式，没有隐式的 sh -c。

• 服务和应用程序在调用前会对照配置的权限进行检查。

• 浏览器方案在打开前会进行验证。

• 桌面输入和截图是独立的选择加入能力，具有受限的输入/输出。

完整契约请参阅 SPEC.md。

开发

corepack pnpm@11.20.0 typecheck
corepack pnpm@11.20.0 test
corepack pnpm@11.20.0 build
corepack pnpm@11.20.0 gate

GitHub Actions 在推送和拉取请求上运行相同的门禁，并对安装程序脚本进行语法检查。

平台限制

• 具体适配器面向 Linux。

• process.list 使用 ps。

• service.* 默认使用 systemd 的 systemctl。

• input.* 使用 xdotool；原生 Wayland 可能需要 XWayland 或未来的特定合成器适配器。

• screen.capture 支持常见的 Linux 截图命令；桌面/会话权限仍然适用。

• 自动安装程序面向 Linux amd64/arm64 和 systemd 用户服务。

• 外部 ChatGPT/隧道冒烟测试需要操作者自己的 OpenAI 隧道身份/运行时凭据；仓库 CI 无法冒充它们。

上游参考

• MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

• MCP 规范: https://modelcontextprotocol.io/specification/2026-07-28

• OpenAI Secure MCP Tunnel: https://developers.openai.com/api/docs/guides/secure-mcp-tunnels

• OpenAI tunnel-client: https://github.com/openai/tunnel-client

• OpenAI 隧道管理: https://platform.openai.com/settings/organization/tunnels

• OpenAI 运行时 API 密钥: https://platform.openai.com/settings/organization/api-keys

• ChatGPT Developer Mode: https://developers.openai.com/api/docs/guides/developer-mode