ChatGPT Local Reader

中文说明 · Windows tutorial · Security

A self-hosted, read-only MCP server that lets ChatGPT's web interface search and read explicitly approved local project files for analysis and planning. No file writing, deletion, shell execution, or model API calls are implemented. This is an independent community project, not an official OpenAI product.

ChatGPT web → OpenAI Secure MCP Tunnel → loopback MCP server → approved folder

Files remain on your computer; content returned by tools is sent to ChatGPT. Only share data you are authorized to disclose. Indexing a file does not mean the model has read it, and indexing is not an upload of the whole directory.

Scope

• Five tools: project_overview, list_project, search, fetch, read_file.

• Explicit root and reviewed path allowlist, or an explicit full-filtered-root opt-in.

• Text/code, Markdown, CSV/JSON/YAML, notebook JSON and DOCX main-body text.

• Bounded reads, secret-pattern filtering and path/link checks. These reduce risk; they are not a perfect data-loss-prevention system or an OS sandbox.

• No PDF, images/OCR, Excel/PowerPoint, media, archives or model weights.

• Windows-first scripts; the Python module can also be tested directly on Linux. See validation results for what was actually tested.

Related MCP server: Local Supervisor Bridge

Quick start — Windows

Prerequisites: Python 3.11+ with venv/pip, PowerShell, and this source folder. Run from the repository root. Git is optional if you downloaded a source ZIP.

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1

$demoRoot = (Resolve-Path .\examples\demo-project).Path
$demoManifest = (Resolve-Path .\examples\demo-allowlist.txt).Path
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\start_local.ps1 -ProjectRoot $demoRoot -Manifest $demoManifest

Keep that terminal open. In a second terminal at the repository root:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\doctor.ps1 -SmokeTest

Then follow ChatGPT connection setup. This requires your own eligible ChatGPT workspace, tunnel permissions, tunnel client and runtime credential. Never use another person's tunnel or paste a credential into a chat. Account eligibility and product usage limits are controlled by OpenAI, not this tool.

Read your own folder

Start with a separate, reviewed share folder. Copy examples/allowlist.example.txt to your own local configuration location and edit the paths. Paths in the allowlist are relative to the target folder, not the allowlist file.

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\start_local.ps1 -ProjectRoot 'C:\Shared\MyProject' -Manifest 'C:\Shared\reader-allowlist.txt'

An explicit -FullFilteredProject may replace -Manifest; it permits all files under that root that pass the filters, including matching files added later. It is not recommended for a home folder, disk root or a mixed private workspace. Switching folders/manifests requires a restart. File edits refresh lazily; configuration details explain the limits.

Develop and verify

.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe scripts\integration_test.py
.\.venv\Scripts\python.exe scripts\check_release.py

Tests use synthetic temporary data. integration_test.py uses its own loopback port and server process, not a running production service. Dependencies are version-pinned in requirements.lock; this is not a hash-verified lock file. Do not interpret a passing test suite as a guarantee against every attack.

Documentation

• Step-by-step Windows guide

• ChatGPT and official tunnel

• Configuration, coverage and file formats

• Troubleshooting

• Threat model and security boundaries

• Review and test report

• Publishing checklist

• Related projects

The optional Codex integration is not required for ChatGPT web. Publishing this code on GitHub for self-hosting is different from submitting a public ChatGPT plugin. Secure MCP Tunnel supports private connections, not public plugin distribution; see the official guide.

License

MIT — see LICENSE. Third-party packages and the separately downloaded official tunnel client retain their own licenses.