Filesystem MCP

Servidor Filesystem MCP

Resumen

Filesystem-MCP es un servidor de Model Context Protocol que permite a los asistentes de IA leer y escribir archivos dentro de directorios explícitamente permitidos. Los patrones de archivos sensibles (.env, *.pem, *id_rsa*) están bloqueados por defecto. Expone herramientas, recursos y prompts del sistema de archivos a través de stdio o transporte HTTP Streamable.

Aspecto	Detalles
Estado	Activo (consulta la insignia npm para la versión actual)
Lenguaje	TypeScript (estricto)
Runtime	Node.js >= 24
Paquete	npm
Licencia	MIT

Características

Característica	Descripción
Protección de rutas	Cada ruta se valida contra las raíces permitidas; .env, *.pem, *id_rsa* y patrones similares se deniegan
Herramientas del sistema de archivos	Navega, inspecciona, lee y escribe en todas las operaciones principales de archivos
Operaciones por lotes	La mayoría de las herramientas aceptan path, paths[], o files[] para ejecución en paralelo
Transporte dual	stdio por defecto; --port habilita HTTP Streamable para clientes de la era 2025 y 2026-07-28
Suscripciones a archivos	Las suscripciones a recursos envían notificaciones de cambio cuando los archivos observados se actualizan
Seguridad de regex	RE2 en todas las herramientas de búsqueda: coincidencia en tiempo lineal, por lo que ningún patrón puede causar ReDoS en el servidor

Comparación con el servidor de referencia

Cómo se diferencia este servidor de @modelcontextprotocol/server-filesystem, verificado contra su README y código fuente el 2026-09-24:

Capacidad	filesystem-mcp	Servidor de referencia
Búsqueda dentro de archivos	search_text: regex RE2 o literal, tiempo lineal	Ninguna; search_files solo coincide con nombres
Archivos secretos	.env, *.pem, *id_rsa* denegados por defecto	No bloqueados
Modo solo lectura	--read-only elimina toda herramienta de mutación	Docker ro solo montajes
Aplicar un diff unificado	patch	Ninguno
Comparar dos archivos	diff	Ninguno
Reemplazar en muchos archivos	replace_text sobre un glob	Ninguno
Observar archivos	Las suscripciones a recursos envían notificaciones de cambio	Sin recursos
Transporte	stdio, o HTTP Streamable con --port	stdio

Construido con

Capa	Tecnología
Protocolo	MCP SDK v2 (@modelcontextprotocol/server)
Runtime	Node.js >= 24 · TypeScript 6 · ESM
Transporte	stdio (por defecto) · HTTP Streamable (--port)
Regex	RE2 (re2-wasm) — tiempo lineal, sin lookahead/lookbehind/backreferences
Contenedor	Docker alpine · compilación multi-etapa · usuario no root

Tabla de contenidos

• Inicio rápido
• Uso
• Estructura del proyecto
• Configuración
• Scripts
• Seguridad
• Contribuciones
• Política de privacidad
• Licencia

Inicio rápido

[!NOTA] Requiere Node.js ≥ 24.

Requisitos previos

Requisito	Versión / Notas
Node.js	≥ 24
npm	Incluido con Node.js
Docker	Opcional — para uso en contenedor

Instalar vía npx

npx -y @j0hanz/filesystem-mcp /path/to/allowed/dir

O instalar globalmente:

npm install -g @j0hanz/filesystem-mcp
filesystem-mcp /path/to/allowed/dir

Instalar vía Docker

docker run -i --rm \
  -v /path/to/project:/workspace:ro \
  ghcr.io/j0hanz/filesystem-mcp:latest \
  --read-only /workspace

Configurar en VS Code

Agregar a .vscode/mcp.json:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

O instalar vía CLI:

code --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","/path/to/project"]}'

Configurar en Visual Studio

Agregar a .vs\mcp.json en el directorio de tu solución, o %USERPROFILE%\.mcp.json para una configuración global:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

Configurar en Claude Desktop

Un clic: descarga filesystem-mcp.mcpb, ábrelo con Claude Desktop y elige los directorios a permitir. El Node.js integrado de Claude Desktop lo ejecuta.

O configúralo manualmente. Agrega a tu claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

Instalar en Cursor

Agrega a .cursor/mcp.json en la raíz de tu proyecto (con alcance de proyecto), o ~/.cursor/mcp.json para una configuración global:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

Instalar como plugin

El plugin filesystem-mcp conecta el servidor con valores predeterminados con alcance de proyecto:

Cliente	Instalación
Claude Code	/plugin marketplace add j0hanz/j0hanz-marketplace, luego /plugin install filesystem-mcp@j0hanz-marketplace
Copilot CLI	copilot plugin marketplace add j0hanz/j0hanz-marketplace, luego copilot plugin install filesystem-mcp@j0hanz-marketplace
Antigravity CLI	git clone https://github.com/j0hanz/j0hanz-marketplace, luego agy plugin install ./j0hanz-marketplace/plugins/filesystem-mcp

El README del plugin cubre los valores predeterminados y cómo cada cliente elige el directorio del proyecto.

Configuración de Docker

VS Code (.vscode/mcp.json) y Visual Studio (.vs\mcp.json):

{
  "servers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/project:/workspace",
        "ghcr.io/j0hanz/filesystem-mcp:latest",
        "/workspace"
      ]
    }
  }
}

Claude Desktop (claude_desktop_config.json) y Cursor (mcp.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/project:/workspace",
        "ghcr.io/j0hanz/filesystem-mcp:latest",
        "/workspace"
      ]
    }
  }
}

[!NOTA] Para privilegio mínimo, usa ambos controles: :ro hace que el montaje del contenedor sea de solo lectura en el límite del sistema operativo, mientras que la bandera --read-only del servidor elimina las herramientas de mutación (create, edit, move, delete, patch, replace_text) de tools/list.

Uso

Herramientas

Todas las herramientas están limitadas a las raíces configuradas. Llama a list_roots primero para descubrir qué está permitido.

Navegar

Herramienta	Descripción
list_roots	Lista las raíces de espacio de trabajo permitidas. Llama a esto primero — todas las demás herramientas se limitan a estas.
list	Lista el contenido del directorio. Devuelve entradas (directorios primero, alfabético) y un árbol ASCII.
find_files	Encuentra archivos por patrón glob (p. ej. **/*.ts). Devuelve archivos coincidentes con metadatos.

Inspeccionar

Herramienta	Descripción
stat	Obtén metadatos de archivo/directorio: tamaño, tiempo de modificación, permisos, tipo MIME, estimación de tokens.
search_text	Busca contenido de archivos por texto (similar a grep). Devuelve líneas coincidentes con contexto.
diff	Compara dos archivos y devuelve un diff unificado con conteos de líneas agregadas/eliminadas.

Leer

Herramienta	Descripción
read	Lee un archivo de texto. Admite rangos de head/tail y de líneas. Acepta paths[] para lotes.

Escribir

Herramienta	Descripción
create	Crea uno o más archivos, creando directorios padre según sea necesario. Un archivo existente solicita al usuario confirmar la sobrescritura; overwrite: true en una entrada omite la solicitud, append: true agrega al final en su lugar.
edit	Aplica reemplazos de cadenas literales secuenciales a uno o más archivos (hasta 5 archivos por llamada, 100 ediciones por archivo).
move	Mueve, renombra o copia (copy: true) uno o más archivos/directorios a destinos explícitos.
delete	Elimina permanentemente uno o más archivos o directorios. Esta acción es irreversible.
replace_text	Búsqueda y reemplazo masivo en archivos que coinciden con un patrón glob.
patch	Aplica un diff unificado de un solo archivo y escribe el resultado.

Recursos

URI	Descripción
internal://instructions	Guía de navegación del servidor — resumen de herramientas, restricciones y recuperación de errores.
filesystem-mcp://file/{+path}	Lee un archivo del espacio de trabajo. Suscríbete para recibir notificaciones push al cambiar.
filesystem-mcp://result/{id}	Salida de herramienta en caché efímera. Expira después de ~60 segundos, desalojo o reinicio del servidor.

Prompts

Prompt	Descripción
get-help	Devuelve instrucciones de uso, opcionalmente filtradas a una sección específica.

Estructura del proyecto

filesystem-mcp/
├── __tests__/          Test suites (node --test) and shared helpers
├── docs/adr/           Architecture decision records
├── mcpb/manifest.json  Claude Desktop extension manifest
├── scripts/            Release-path scripts (MCPB pack, Smithery publish)
├── src/
│   ├── core/           Path guarding, filesystem facade, search, stores, watchers
│   ├── tools/          One file per tool, plus define.ts (registration) and batch.ts
│   ├── transport/      stdio.ts, http.ts, http-policy.ts (auth, Origin, rate limit), shared.ts
│   ├── cli.ts          Argument parsing and --print-config
│   ├── cli-help.ts     --help / --version text
│   ├── index.ts        Process entrypoint, shutdown, transport selection
│   ├── instructions.ts Server instructions sent to every client
│   ├── prompts.ts      Prompt definitions and registration
│   ├── resources.ts    Resource definitions, subscriptions, completion
│   ├── server.ts       Server factory and registrar composition
│   └── transport.ts    Facade re-exporting startServer / startHttpServer
└── Dockerfile          Multi-stage alpine build, non-root user

La composición del runtime fluye desde src/index.ts a src/transport/ (stdio o HTTP), luego a src/server.ts, los registradores y finalmente src/core/. Cada registrador posee el contrato de dependencia estrecho que consume.

Ruta	Propósito
src/core/path.ts	PathGuard — valida cada ruta contra las raíces permitidas
src/core/fs.ts	GuardedFileSystem — fachada de sistema de archivos protegida
src/tools/define.ts	Marco de registro y ejecución de herramientas
src/tools/batch.ts	Ayudantes de lote (runOverPaths, isTotalFailure)
src/server.ts	Construye dependencias compartidas e invoca a los tres registradores
src/transport/	stdio (stdio.ts), Streamable HTTP (http.ts), política HTTP (http-policy.ts)

Configuración

El servidor inicia con directorios permitidos desde la configuración explícita de arranque:

1. Directorios posicionales pasados a filesystem-mcp.
2. Variable de entorno FS_ALLOWED_DIRS (separados por : en POSIX o ; en Windows).
3. Directorio de trabajo actual cuando --allow-cwd está habilitado.

Las conexiones MCP heredadas pueden además sembrar raíces mediante el flujo obsoleto de roots/list. Las conexiones modernas de 2026-07-28 no envían automáticamente raíces del espacio de trabajo. Pueden añadir acceso después del arranque llamando a una herramienta con una ruta concreta y aprobando la concesión respaldada por elicitación. list_roots informa las raíces ya configuradas o aceptadas; no puede descubrir un espacio de trabajo desconocido por sí mismo.

Sobre HTTP, los clientes de la era 2025 se atienden sin estado: herramientas, recursos y prompts funcionan. Las confirmaciones (borrado recursivo, sobrescritura, concesiones de acceso) requieren un cliente de 2026-07-28 o stdio y responden con un error de herramienta indicándolo; las suscripciones a archivos no se anuncian en esa vía, y un resources/subscribe enviado de todos modos se rechaza con método-no-encontrado.

Recetas globales recomendadas

VS Code / Cursor / Claude Code (receta principal)

Configure el directorio del proyecto explícitamente:

Añada a su configuración global o de ámbito de proyecto:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
    }
  }
}

Claude Desktop (receta alternativa mediante variable de entorno)

Claude Desktop y clientes similares no admiten el protocolo MCP Roots. Use la variable de entorno FS_ALLOWED_DIRS para configurar las carpetas permitidas.

Añada a su claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest"],
      "env": {
        "FS_ALLOWED_DIRS": "/path/to/project1:/path/to/project2"
      }
    }
  }
}

(En Windows, separe los directorios con un punto y coma ; en lugar de dos puntos :).

Argumentos posicionales avanzados / por proyecto

También puede restringir el acceso a directorios específicos pasando argumentos posicionales directamente:

# Start with explicit positional paths
filesystem-mcp /path/to/project1 /path/to/project2

---

Referencia de configuración

Banderas de CLI

Bandera	Predeterminado	Propósito
[dirs...]	—	Una o más raíces de directorio permitidas (posicional). Un argumento completo ${NAME} se lee del entorno y se descarta si no está definido
--allow-cwd	false	Permitir también el directorio de trabajo actual como raíz
--walk-cwd	false	Ascender desde el CWD para encontrar una raíz de proyecto; implica --allow-cwd
--allow-missing-roots	false	Iniciar incluso si los directorios permitidos configurados no existen
--port <n>	—	Habilitar transporte HTTP Streamable en el puerto dado (env: FS_PORT)
--http-host <host>	—	Dirección de enlace del servidor HTTP (env: FS_HTTP_HOST)
--api-key <key>	—	Requerir esta clave API en solicitudes HTTP (env: FS_API_KEY)
--read-only	false	Deshabilitar herramientas de escritura: create, edit, delete, move, patch, replace_text
--deny <pattern>	—	Bloquear rutas que coincidan con este patrón; repetible
--allow <pattern>	—	Eximir un patrón de la lista de denegación sensible integrada; repetible (env: FS_ALLOWLIST). No levanta entradas de --deny/FS_DENYLIST
--allow-sensitive	false	Permitir acceso a rutas sensibles del sistema (env: FS_ALLOW_SENSITIVE)
--root-boundary <path>	—	Requerir que todas las raíces permitidas caigan bajo esta ruta (env: FS_ROOT_BOUNDARY)
--max-file-size <bytes>	—	Tamaño máximo de archivo para lecturas en bytes (env: FS_MAX_FILE_SIZE)
--log-level <level>	info	Nivel de registro RFC 5424, debug hasta emergency (env: FS_LOG_LEVEL)
--print-config	false	Imprimir la configuración activa como JSON y salir

Los patrones de --deny y --allow admiten * (cualquier ejecución dentro de un segmento), ** (cualquier ejecución de segmentos), ?, clases de [...] y alternancia de {a,b}. Los nombres que comienzan con punto (ocultos) coinciden como cualquier otro — secrets/** deniega secrets/.env, *id_rsa* deniega .id_rsa.

Variables de entorno

Todas las variables booleanas aceptan true o 1 para habilitar y false, 0, o sin definir para deshabilitar; cualquier otro valor registra una advertencia y se lee como deshabilitado. Las banderas tienen prioridad cuando ambas están definidas.

Variable	Propósito
FS_ALLOWED_DIRS	Lista de directorios permitidos separados por dos puntos (POSIX) o punto y coma (Windows).
FS_ROOT_BOUNDARY	Prefijo de ruta bajo el cual deben ubicarse todas las raíces permitidas (refleja --root-boundary).
FS_ALLOW_CWD_WALK	Subir desde el directorio de trabajo actual para encontrar una raíz de proyecto (refleja --walk-cwd).
FS_ALLOW_MISSING_ROOTS	Iniciar incluso si los directorios configurados no existen (refleja --allow-missing-roots).
FS_ALLOW_SENSITIVE	Permitir acceso a rutas sensibles del sistema (refleja --allow-sensitive).
FS_DENYLIST	Lista separada por comas de rutas o patrones a bloquear (refleja --deny).
FS_ALLOWLIST	Patrones separados por comas exentos de la lista de denegación sensible incorporada (refleja --allow). Nunca elimina las entradas de FS_DENYLIST/--deny.
FS_MAX_FILE_SIZE	Tamaño máximo de archivo para lecturas en bytes (refleja --max-file-size).
FS_LOG_LEVEL	Nivel de registro RFC 5424: debug, info, notice, warn/warning, error, critical, alert o emergency (refleja --log-level).
FS_PORT	Iniciar el transporte HTTP Streamable en este puerto; sin definir = stdio (refleja --port).
FS_HTTP_HOST	Dirección de enlace del servidor HTTP (refleja --http-host).
FS_API_KEY	Clave API requerida en solicitudes HTTP (refleja --api-key).
FS_TRUST_PROXY	Configuración de Express trust proxy: número de saltos o expresión. Sin definir = no confiar en X-Forwarded-*.
FS_ALLOWED_HOSTS	Valores de encabezado Host separados por comas para aceptar (transporte HTTP).
FS_ALLOWED_ORIGINS	Nombres de host de origen separados por comas permitidos para llamar a /mcp desde un navegador. Reemplaza el valor predeterminado de localhost, así que también liste localhost, 127.0.0.1 o [::1] si los clientes de navegador locales aún necesitan acceso.
FS_ALLOW_UNRESTRICTED_HOSTS	Enlazar un host comodín sin validación de Host (acepta el riesgo).
FS_PUBLIC_URL	URL de identificador de recurso para descubrimiento RFC 9728.
FS_RATE_LIMIT_RPM	Solicitudes por minuto por IP de cliente (predeterminado 120 con autenticación de clave API, 6,000 para loopback sin clave; rango 1–100000).
FS_MAX_WATCHERS	Máximo de observadores de archivos concurrentes (predeterminado 256, 1–4096).
NO_COLOR	Cualquier valor desactiva la salida de color ANSI.
FS_REQUEST_STATE_KEY	Clave HMAC que sella input_required requestState entre rondas de reintento. Opcional (aleatoria por arranque si no se define); establézcala, con al menos 32 bytes UTF-8, para mantener vivas las rondas en curso a través de un reinicio.

Ejemplos

# Allow current working directory
filesystem-mcp --allow-cwd

# HTTP transport on port 3000
filesystem-mcp --port 3000

Scripts

Modo	Comando	Descripción
Verificación completa	npm run check	Ejecutar compilación, verificación de tipos, lint, formato, knip y pruebas
Auto-corrección + verificación	npm run fix	Auto-corregir formato/lint y ejecutar la verificación completa
Solo estático	npm run check:static	Ejecutar análisis estático sin pruebas
Solo pruebas	npm test	Ejecutar pruebas; acepta opciones nativas de node --test

Seguridad

[!IMPORTANT] Reporte vulnerabilidades de forma privada a través de GitHub Security Advisories. No abra problemas públicos para informes de seguridad.

Tema	Detalle
Travesía de rutas	Cada ruta se resuelve y valida contra las raíces permitidas antes de cualquier operación
Archivos sensibles	.env, *.pem, *id_rsa* y patrones similares se deniegan por defecto
Seguridad de regex	RE2 no puede retroceder, por lo que un patrón hostil no puede colgar el servidor (ReDoS)
Contenedor	Se ejecuta como usuario no root mcp; los montajes de enlace controlan lo que se expone

Contribución

1. Haga un fork del repositorio.
2. Cree una rama de características: git checkout -b feat/your-feature.
3. Confirme sus cambios con un mensaje claro.
4. Ejecute npm run check para confirmar que pruebas, tipos, lint, formato y knip pasen.
5. Abra una solicitud de extracción.

Política de privacidad

filesystem-mcp se ejecuta completamente en su máquina. Esta política cubre el paquete npm, la imagen Docker y la extensión de escritorio .mcpb.

• Recopilación de datos: ninguna. El servidor no tiene telemetría, análisis ni informes de fallos, y no realiza solicitudes de red salientes.
• Uso y almacenamiento: los archivos se leen y escriben solo dentro de los directorios que usted permite, y solo cuando su cliente MCP llama a una herramienta. Los resultados de las herramientas van a ese cliente y a ningún otro lugar. Las cachés de resultados de corta duración viven en memoria y desaparecen cuando el servidor se cierra.
• Compartición con terceros: ninguna por parte de este servidor. Su cliente MCP puede enviar resultados de herramientas a su proveedor de modelos bajo la propia política de privacidad de ese cliente.
• Retención: nada se conserva después de que el proceso se cierra. Los registros de diagnóstico van a stderr en su máquina; su cliente MCP puede guardarlos en sus propios archivos de registro.
• Contacto: abra un problema en https://github.com/j0hanz/filesystem-mcp/issues, o reporte problemas de seguridad de forma privada a través de GitHub Security Advisories.

Licencia

Publicado bajo la Licencia MIT. Consulte LICENSE para más detalles.