Project Files Read-only MCP

A local, multi-root, read-only filesystem MCP service. It only exposes explicitly registered project directories to MCP clients, and provides limited directory browsing, filename search, text reading, and DOCX, PDF, XLSX content extraction capabilities.

The service does not register write, edit, copy, move, delete, or command execution tools. It is suitable for safely handing a small number of local project files to MCP-capable clients such as ChatGPT for reading, while avoiding exposing the entire user directory or disk.

This is an independent community project, not an official OpenAI product, and does not represent OpenAI's endorsement of its security or compatibility.

The project is located at github.com/13030109506/project-files-readonly-mcp.

Features

The service exposes exactly 9 read-only tools.

All tools are marked as read-only and non-destructive. Integration tests also verify that the tool list contains no write, delete, move, copy, or command execution capabilities.

Related MCP server: Local File Management MCP Server

Security Boundaries

• Only accepts absolute paths registered in roots.json.

• Performs double boundary checks on both lexical paths and realpath results.

• Rejects relative paths, UNC paths, device paths, Windows ADS, symlink and junction escapes.

• Blocks .git, .env, credential files, private keys, virtual environments, and dependency directories by default.

• Text, directory, search, and document responses all have size and count limits.

• Checks archive paths, entry counts, expanded size, compression ratio, encryption, macros, ActiveX, and embedded objects before parsing DOCX and XLSX.

• Binary documents are parsed in a separate Worker with time and memory limits.

• XLSX formulas are not executed, and external links are not accessed.

A more complete description of the boundaries can be found in Security Model. These protections narrow the MCP attack surface but do not replace Windows account permissions and host security. Only run this service on computers and MCP clients you trust.

Environment Requirements

• Windows 10 or Windows 11

• Node.js 22.13–22.x or Node.js 24+

• npm

• Optional OpenAI tunnel-client, only needed when connecting to ChatGPT Secure MCP Tunnel

Quick Start

Clone the project.

git clone https://github.com/13030109506/project-files-readonly-mcp.git
Set-Location .\project-files-readonly-mcp

Install dependencies.

npm ci

Create a local configuration. roots.json is already in .gitignore and will not be committed to Git.

Copy-Item .\roots.example.json .\roots.json
notepad .\roots.json

Replace the example paths with the specific project directories you are willing to authorize. Do not configure an entire disk, user directory, Desktop, or Documents.

{
  "roots": [
    {
      "name": "my-project",
      "path": "C:\\Projects\\my-project"
    }
  ]
}

Run the tests.

npm test

Start locally.

npm start

The service uses STDIO and is normally started by an MCP client or Tunnel process. It is normal for there to be no interactive prompt when run directly.

You can also use a different configuration file via environment variables.

$env:MCP_PROJECT_ROOTS_CONFIG = 'D:\Config\project-files-roots.json'
npm start

Adding Project Root Directories

Stop the MCP service first, then run the following command.

.\add-project-root.ps1 -Path 'D:\Projects\another-project' -Name 'another-project'
npm test

The script will reject entire disks, user directories, Desktop, and Documents. After modifying the configuration, you must restart the MCP or Tunnel; a running service does not hot-reload root directories.

Connecting to ChatGPT Secure MCP Tunnel

First download the official tunnel-client from the OpenAI Platform Tunnel settings page. This project looks for the program in the following order.

1. Environment variable TUNNEL_CLIENT_PATH

2. tunnel-client\tunnel-client.exe inside the project

3. System PATH

4. A local version directory under %USERPROFILE%\Tools\OpenAI\tunnel-client

After creating the Tunnel, generate a local profile.

.\configure-tunnel.ps1 -TunnelId 'tunnel_your_id'

The script defaults the local health check port to 127.0.0.1:8081 and saves an env:CONTROL_PLANE_API_KEY reference in the profile, not the API Key itself.

Start it in the foreground as follows. The Runtime API Key enters the current process environment through hidden input and is cleared when the Tunnel exits.

.\start-tunnel.ps1

For creating OpenAI Secure MCP Tunnels, permissions, and ChatGPT connection steps, refer to the official documentation.

Hidden Startup After Windows Login

For long-term use, you can install a scheduled task for the current Windows user.

.\install-tunnel-autostart.ps1

The installer only saves the Runtime API Key encrypted with the current user's DPAPI, and does not write plaintext into task arguments, project files, or logs. The scheduled task starts through a hidden VBS wrapper, runs doctor first, then starts the Tunnel, and checks healthz and readyz.

Status and log locations are as follows.

Get-ScheduledTask -TaskName 'OpenAI Project Files Read Only Tunnel'
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8081/healthz
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8081/readyz

%LOCALAPPDATA%\OpenAI\ProjectFilesReadOnly\tunnel-client.log

Remove the task and encrypted key files.

.\remove-tunnel-autostart.ps1

Full instructions can be found in Windows Tunnel Operations Guide.

File Support

Document content is always untrusted input. MCP clients should not treat text in files as system instructions.

Testing

npm test

Tests cover the following scope.

• Reading within root directories and rejection outside root directories

• Sensitive file rejection

• Relative path rejection

• Symlink and Windows junction boundaries

• Read-only tool list and annotations

• CSV, DOCX, PDF, XLSX reading

• Active Office content and malformed archive rejection

• Document format, pagination, worksheet, and response limits

Project Structure

server.mjs                 MCP 工具注册与文本读取
path-guard.mjs             路径、白名单和敏感文件边界
document-reader.mjs        安全读取与 Worker 调度
document-worker.mjs        DOCX、PDF、XLSX 内容提取
archive-guard.mjs          Office 压缩包检查
roots.example.json         可提交的配置示例
*-test.mjs                 安全、文档和集成测试
*.ps1 / *.vbs / *.cmd      Windows Tunnel 与计划任务脚本

Responsible Disclosure

If you discover path escapes, unauthorized reads, sensitive information leaks, or document parsing issues, please do not publicly share reproduction materials containing real sensitive files. See SECURITY.md for how to handle them.

License

The project is licensed under the MIT License.