mcplocal

Servidor MCP de archivos locales que permite a un cliente compatible con MCP (incluidas las aplicaciones MCP personalizadas de ChatGPT Web cuando estén disponibles) leer, buscar y modificar archivos dentro de un directorio configurado explícitamente.

Características

• HTTP+SSE heredado: GET /sse + POST /messages

• Punto de conexión HTTP MCP moderno: /mcp

• Comprobación de estado: /health

• Sandbox: cada ruta de archivo se resuelve dentro de MCP_ROOT

• Autenticación Bearer opcional

• Herramientas de lectura/búsqueda para el descubrimiento de proyectos

• Herramientas de escritura/edición para flujos de trabajo de codificación

• El borrado está deshabilitado por defecto

• Sin herramienta de ejecución de shell/CLI

• Sin dependencia de una base de datos externa

• Node.js 20+

El SDK de TypeScript de MCP recomienda actualmente Streamable HTTP para servidores remotos y trata HTTP+SSE como un transporte de compatibilidad hacia atrás. Este proyecto expone intencionadamente ambos para que los clientes SSE más antiguos puedan seguir conectándose mientras que los clientes más nuevos puedan usar /mcp.

Related MCP server: FilesystemMCP

1. Ejecutar

cp .env.example .env
# edit MCP_ROOT if needed
npm start

Ejemplo:

MCP_ROOT=~/Projects
MCP_HOST=127.0.0.1
MCP_PORT=8008
MCP_AUTH_TOKEN=change-me

Luego:

SSE:        http://127.0.0.1:8008/sse
Streamable: http://127.0.0.1:8008/mcp
Health:     http://127.0.0.1:8008/health

2. A qué puede conectarse ChatGPT Web

ChatGPT Web no puede acceder directamente a localhost desde el servicio alojado. Un servidor MCP local debe hacerse accesible a través del mecanismo compatible de Secure MCP Tunnel/red privada. Después de tener un punto de conexión MCP remoto, agrégalo como una aplicación MCP personalizada en el modo de desarrollador de ChatGPT, escanea sus herramientas y actívalo.

Para un túnel que asigne el servicio local, el origen local es:

http://127.0.0.1:8008/sse

o, para clientes modernos:

http://127.0.0.1:8008/mcp

No expongas este servidor a Internet público sin autenticación y una política de red explícita.

3. Herramientas expuestas a ChatGPT

• list_files(path, recursive)

• read_file(path, startLine, endLine)

• write_file(path, content, createDirs)

• edit_file(path, oldText, newText, replaceAll)

• search_files(query, path, regex, caseSensitive, maxResults)

• create_directory(path)

• file_info(path)

• delete_file(path) solo cuando MCP_ENABLE_DELETE=true

Flujo de trabajo de codificación típico:

1. list_files para entender el proyecto.

2. search_files para localizar símbolos.

3. read_file para inspeccionar el código relevante.

4. edit_file para un cambio quirúrgico, o write_file para un archivo nuevo.

5. read_file de nuevo para verificar el resultado.

4. Modelo de seguridad

MCP_ROOT es el límite estricto. Se rechazan los recorridos ../ y las rutas absolutas fuera de él. Los archivos binarios/ilegibles se omiten en la búsqueda. El tamaño de los archivos está limitado por MCP_MAX_FILE_BYTES.

El servidor no expone intencionadamente la ejecución arbitraria de shell. Eso significa que ChatGPT puede editar código pero no puede ejecutar automáticamente rm, curl, gestores de paquetes, comandos git ni programas arbitrarios a través de este MCP.

Para una máquina de desarrollo, mantén MCP_HOST=127.0.0.1 y usa el Secure MCP Tunnel compatible en lugar de vincular el servidor a todas las interfaces.

5. Compilar

npm run build
node dist/server.js

La compilación no tiene dependencias y copia el tiempo de ejecución en dist/.

6. Docker

docker build -t mcplocal .
docker run --rm -p 8008:8008 -v "$PWD:/workspace" mcplocal

7. Ejemplos de indicaciones en ChatGPT

Inspect this local project and tell me where the authentication flow is implemented. Do not modify anything.

Open src/server.js and refactor the error handling. Before changing it, read the relevant code. Then edit only the necessary section and show me what changed.

Search the project for TODO comments and create a report at reports/todos.md.

Licencia

MIT