Project Files Read-only MCP

Un servicio MCP de sistema de archivos local, de solo lectura y con múltiples directorios raíz. Solo expone a los clientes MCP los directorios de proyecto registrados explícitamente, y ofrece capacidades limitadas de navegación de directorios, búsqueda de nombres de archivo, lectura de texto y extracción de contenido de DOCX, PDF y XLSX.

El servicio no registra herramientas de escritura, edición, copia, movimiento, eliminación o ejecución de comandos. Es adecuado para entregar de forma segura unos pocos archivos de proyectos locales a clientes compatibles con MCP como ChatGPT para su lectura, evitando al mismo tiempo exponer todo el directorio de usuario o el disco.

Este es un proyecto comunitario independiente, no es un producto oficial de OpenAI ni representa un respaldo de OpenAI a su seguridad o compatibilidad.

La dirección del proyecto es github.com/13030109506/project-files-readonly-mcp.

Funciones

El servicio expone de forma fija 9 herramientas de solo lectura.

Todas las herramientas están marcadas como de solo lectura y no destructivas. Las pruebas de integración también verifican que la lista de herramientas no contenga capacidades de escritura, eliminación, movimiento, copia o ejecución de comandos.

Related MCP server: Local File Management MCP Server

Límites de seguridad

• Solo acepta rutas absolutas registradas en roots.json.

• Realiza una doble verificación de límites tanto del camino léxico como del resultado de realpath.

• Rechaza rutas relativas, rutas UNC, rutas de dispositivos, ADS de Windows, escapes mediante enlaces simbólicos y puntos de unión.

• Bloquea por defecto .git, .env, archivos de credenciales, claves privadas, entornos virtuales y directorios de dependencias.

• Las respuestas de texto, directorios, búsquedas y documentos tienen límites de tamaño y cantidad.

• Antes de analizar DOCX y XLSX, se verifican las rutas del paquete comprimido, el número de entradas, el volumen de expansión, la relación de compresión, el cifrado, las macros, ActiveX y los objetos incrustados.

• Los documentos binarios se analizan en un Worker independiente con límites de tiempo y memoria.

• Las fórmulas de XLSX no se ejecutan y no se accede a enlaces externos.

Una descripción más completa de los límites se encuentra en Modelo de seguridad. Estas protecciones reducen la superficie de invocación de MCP, pero no sustituyen a los permisos de la cuenta de Windows ni a la seguridad del host. Ejecuta este servicio solo en computadoras y clientes MCP de confianza.

Requisitos del entorno

• Windows 10 o Windows 11

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

• npm

• El tunnel-client opcional de OpenAI, solo necesario para conectarse al Secure MCP Tunnel de ChatGPT

Inicio rápido

Clona el proyecto.

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

Instala las dependencias.

npm ci

Crea la configuración local. roots.json ya está incluido en .gitignore y no se enviará a Git.

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

Cambia las rutas de ejemplo por los directorios de proyecto específicos que quieras autorizar. No configures todo el disco, el directorio de usuario, el Escritorio o Documentos.

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

Ejecuta las pruebas.

npm test

Inicio local.

npm start

El servicio usa STDIO y normalmente debe ser iniciado por el cliente MCP o el proceso Tunnel. Es normal que al ejecutarlo directamente no haya indicaciones interactivas.

También se pueden usar otros archivos de configuración mediante variables de entorno.

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

Añadir directorios raíz de proyecto

Detén primero el servicio MCP y luego ejecuta el siguiente comando.

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

El script rechazará todo el disco, el directorio de usuario, el Escritorio y Documentos. Después de modificar la configuración, debes reiniciar MCP o Tunnel; el servicio en ejecución no recarga los directorios raíz en caliente.

Conexión al Secure MCP Tunnel de ChatGPT

Primero descarga el tunnel-client oficial desde la página de configuración de Tunnel de OpenAI Platform. Este proyecto lo busca en el siguiente orden.

1. Variable de entorno TUNNEL_CLIENT_PATH

2. tunnel-client\tunnel-client.exe dentro del proyecto

3. PATH del sistema

4. Directorio de versiones locales en %USERPROFILE%\Tools\OpenAI\tunnel-client

Después de crear el Tunnel, genera el perfil local.

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

El script establece por defecto el puerto de comprobación de salud local en 127.0.0.1:8081 y guarda en el perfil una referencia a env:CONTROL_PLANE_API_KEY, sin almacenar la propia API Key.

La forma de inicio en primer plano es la siguiente. La Runtime API Key entra en el entorno del proceso actual mediante entrada oculta y se elimina al salir del Tunnel.

.\start-tunnel.ps1

La creación del Secure MCP Tunnel de OpenAI, los permisos y los pasos de conexión con ChatGPT se rigen por la documentación oficial.

Inicio oculto tras el inicio de sesión de Windows

Para uso prolongado, se puede instalar una tarea programada para el usuario actual de Windows.

.\install-tunnel-autostart.ps1

El instalador solo guarda la Runtime API Key cifrada con DPAPI del usuario actual y no escribe texto plano en los parámetros de la tarea, archivos del proyecto o registros. La tarea programada se inicia mediante un envoltorio VBS oculto, que primero ejecuta doctor, luego inicia el Tunnel y comprueba healthz y readyz.

Las ubicaciones de estado y registros son las siguientes.

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

Eliminar la tarea y los archivos de clave cifrada.

.\remove-tunnel-autostart.ps1

Instrucciones completas en Guía de operación de Tunnel en Windows.

Compatibilidad de archivos

El contenido de los documentos siempre es entrada no confiable. Los clientes MCP no deben tratar el texto de los archivos como instrucciones del sistema.

Pruebas

npm test

Las pruebas cubren el siguiente alcance.

• Lectura dentro del directorio raíz y rechazo fuera de él

• Rechazo de archivos sensibles

• Rechazo de rutas relativas

• Límites de enlaces simbólicos y puntos de unión de Windows

• Lista de herramientas de solo lectura y anotaciones

• Lectura de CSV, DOCX, PDF, XLSX

• Rechazo de contenido activo de Office y paquetes comprimidos anómalos

• Formatos de documentos, paginación, hojas de cálculo y límites de respuesta

Estructura del proyecto

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 与计划任务脚本

Divulgación responsable

Si encuentras escapes de ruta, lecturas no autorizadas, fugas de información sensible o problemas de análisis de documentos, no publiques públicamente material de reproducción con archivos sensibles reales. El procedimiento se describe en SECURITY.md.

Licencia

El proyecto utiliza MIT License.