# 用 ChatGPT 网页版读取本机文件

在 Windows 上运行一个只读 MCP 服务，通过 OpenAI 安全隧道接入 ChatGPT。连接后，在网页版的普通 Chat 中选中自建插件，即可按需列出、搜索和读取指定文件夹里的文件。

```mermaid
flowchart LR
    Chat["ChatGPT 网页版"] <--> Tunnel["OpenAI 安全隧道"]
    Tunnel <--> Client["本机 tunnel-client"]
    Client <-->|stdio| MCP["Python MCP 服务"]
    MCP --> Folder["你指定的共享目录"]
```

## 1. 准备 Windows 环境

需要 Python 3.11、能创建和使用安全隧道的 OpenAI Platform 账号，以及能添加自定义 MCP 服务器的 ChatGPT 工作区。先确认 [ChatGPT 插件页](https://chatgpt.com/plugins) 的「添加」菜单里有「添加自定义 MCP 服务器」。

从 [Releases](https://github.com/xuy031045-maker/chatgpt-local-files-mcp/releases) 下载 Source code (zip) 并解压，或使用 Git 克隆。随后在项目目录打开 PowerShell：

```powershell
py -3.11 -m venv .venv
& .\.venv\Scripts\python.exe -m pip install -r requirements.txt
& .\.venv\Scripts\python.exe verify.py
```

如果系统没有 `py`，用 `python --version` 确认 `python` 指向 3.11，再用 `python -m venv .venv`。`verify.py` 用临时文件测试 MCP 工具与路径限制，可以离线运行。

从 [OpenAI 官方 tunnel-client 发布页](https://github.com/openai/tunnel-client/releases/latest) 下载符合电脑架构的 Windows ZIP，核对发布页的 `SHA256SUMS.txt` 后解压。例如，在 PowerShell 使用 `Get-FileHash -Algorithm SHA256 <下载的 ZIP 路径>`。记下 `tunnel-client.exe` 的位置。

## 2. 创建隧道和运行密钥

1. 打开 [OpenAI Platform 隧道设置](https://platform.openai.com/settings/organization/tunnels)，创建隧道，将它关联到实际使用的 ChatGPT 工作区，记下 `tunnel_` 开头的隧道 ID。创建或编辑隧道需要 **Tunnels Read + Manage**。
2. 在 [OpenAI Platform API 密钥设置](https://platform.openai.com/settings/organization/api-keys) 创建 **Restricted** 运行密钥，仅赋予 **Tunnels Read + Use**。按需选择到期时间。保存密钥到自己信任的密码管理器。

账号权限或入口随工作区而异。完整的权限和关联要求见 [OpenAI 安全隧道文档](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)。

## 3. 启动本机服务

在项目目录里创建一个专用共享文件夹，先只放一份测试文件。可以将示例文件内容替换成任意一段新文字，测试时只向 ChatGPT 提供文件名。

```powershell
New-Item -ItemType Directory -Path .\shared -Force | Out-Null
Copy-Item .\examples\hello.txt .\shared\hello.txt
& .\.venv\Scripts\python.exe .\start_tunnel.py `
  --root .\shared `
  --tunnel-client 'C:\tools\tunnel-client\tunnel-client.exe' `
  --tunnel-id 'tunnel_REPLACE_WITH_YOUR_ID'
```

把示例里的客户端路径和隧道 ID 换成你的实际值。脚本会在终端中隐藏输入的密钥，只把它交给本次运行的客户端。它会先运行 `doctor`，诊断通过后启动连接。保持终端打开，在浏览器访问 `http://127.0.0.1:8080/ui` 查看状态。若端口被占用，启动时加 `--port 18080` 并使用相应端口查看。按 `Ctrl+C` 停止。

## 4. 在普通 Chat 中试用

1. 在 [ChatGPT 插件页](https://chatgpt.com/plugins) 选择 **添加 → 添加自定义 MCP 服务器**。填写自己的插件名称，例如「项目资料只读」。
2. 连接方式选 **隧道**，选中或填入同一个隧道 ID。这个示例服务未实现额外的 MCP OAuth，因此该表单的身份验证选择 **无需身份验证**。隧道本身仍由 OpenAI Platform 和工作区管理访问权限。
3. 阅读界面提示后创建插件，并在弹窗中连接。保持本机客户端运行，供 ChatGPT 发现工具。
4. 打开普通 Chat，输入 `@项目资料只读` 并在候选列表中选中插件。发送「请读取 `hello.txt`，并原样返回文件内容。」结果应与本机文件一致。

要查询自己的文件，将 `--root` 换成实际共享目录并重启客户端。电脑、网络和客户端都要保持可用。插件只在发起工具调用时获取文件信息，被读取的内容会返回给 ChatGPT 处理。

## 工具与边界

| 工具 | 行为 |
| --- | --- |
| `list_files` | 列出目录中的直接子项，每次最多 200 项 |
| `search_files` | 递归查文件名，可选搜索 UTF-8 文本内容，返回最多 100 个匹配 |
| `read_file` | 读取 UTF-8 文本、常见源代码、PDF、DOCX、XLSX。使用 `offset` 和 `limit` 分页读取文本 |

工具路径一律相对于共享目录。例如 `docs/notes.md`。单文件上限为 5 MB，提取结果最多 120,000 字符。PDF 仅提取文字层，扫描件需要先做 OCR。Office 文件只提取可读文本或单元格缓存值，旧版 DOC/XLS 不支持。

服务会检查目录边界并拒绝链接、目录联接和多重硬链接，过滤 `.env`、密钥扩展名及一些常见凭据文件名。过滤规则无法辨认所有敏感内容，且应用层路径检查不能替代操作系统沙箱。建议只在 `--root` 中放入你愿意让 ChatGPT 读取的文件。

## 常见问题

| 现象 | 检查方法 |
| --- | --- |
| ChatGPT 看不到隧道 | 检查工作区关联和 Tunnels Read + Use 权限，确认客户端已启动 |
| `doctor` 提示鉴权失败 | 检查运行密钥所属组织、权限及是否到期 |
| 本机状态页正常但网页调用失败 | 先访问 `http://127.0.0.1:8080/readyz`，再核对插件所选隧道 ID 与当前启动参数 |
| 搜索不到 PDF 或 Office 正文 | `search_files` 仅全文搜索 UTF-8 文本。先查文件名，再调用 `read_file` |

代码采用 MIT 许可证。OpenAI 隧道客户端从其官方仓库单独下载。