Filesystem MCP — Casos de uso, Instalar & Demo en vivo

Por qué usarlo

Características clave

Aislamiento estricto de rutas — raíces configuradas al inicio, sin escape mediante symlinks o ..
Lectura, escritura, edición por línea, búsqueda de contenido recursiva, árbol de directorios
Compatible con binarios — lee imágenes, PDFs, audio como blobs en base64
Sin configuración — npx -y @modelcontextprotocol/server-filesystem <dir> y listo
Publicado y firmado por el equipo de referencia de MCP

Demo en vivo

Cómo se ve en la práctica

filesystem.replay ▶ listo

0/0

Instalar

Elige tu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  ]
}

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json

{
  "context_servers": {
    "filesystem": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/workspace"
        ]
      }
    }
  }
}

Añádelo a context_servers. Zed recarga en caliente al guardar.

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /workspace

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: Filesystem

Cómo refactorizar una función en toda la base de código sin romper nada

👤 Ingenieros que renombran/reconfiguran una API que se usa en muchos archivos ⏱ ~20 min intermediate

Cuándo usarlo: Necesitas renombrar una función, cambiar su firma o inlinear un helper — y se usa en 30+ archivos en todo el repositorio.

Requisitos previos

Árbol de trabajo git limpio — git status no muestra nada staged — para que puedas usar git diff para revisar y git restore si es necesario
Raíz del filesystem limitada al repositorio — Inicia con npx -y @modelcontextprotocol/server-filesystem /abs/path/to/repo

Flujo

Encuentra cada sitio de llamada

Busca en la base de código cada uso de getUserProfile(. Agrupa los resultados por archivo y dame un conteo por archivo.✓ Copiado

→ Lista de archivos con conteos de coincidencias, sin distinguir entre tests y código fuente
Ensayo de la edición en un archivo

Muéstrame cómo se vería la edición en src/api/users.ts — un diff, no el archivo completo. No escribas aún.✓ Copiado

→ Parche diff mínimo, no una reescritura completa del archivo
Aplica a todos los archivos e informa

Aplica la misma transformación a cada archivo del paso 1. Usa edit_file (a nivel de línea), no write_file (sobrescribir). Cuéntame cualquier archivo donde el patrón no coincidiera limpiamente.✓ Copiado

→ Log de éxito/omisión por archivo

Resultado: Un diff de git enfocado y revisable en el que puedas ejecutar pruebas — sin reescrituras sorpresa de archivos completos.

Errores comunes

Claude usa write_file y silenciosamente pierde la mitad del archivo cuando la edición es compleja — Requiere explícitamente edit_file para cambios in-place; permite write_file solo para archivos creados nuevos
Las coincidencias afectan código no relacionado (p. ej. getUserProfileAvatar) — Ancla la búsqueda: getUserProfile( con el paréntesis final, o usa una regex de límite de palabra

Combinar con: git · github

Triaje de un crash leyendo archivos de log de producción localmente

👤 Ingenieros de guardia con logs en disco ⏱ ~15 min beginner

Cuándo usarlo: Has descargado un paquete de logs de un incidente de cliente y necesitas encontrar la aguja sin habilidades de grep.

Requisitos previos

Logs en disco — Descarga/descomprime bajo una carpeta dedicada /incidents/<ticket>/

Flujo

Obtén una descripción general estructural

Lista los archivos bajo /incidents/TICKET-1234/. Para cada archivo de log, muestra el tamaño y la primera + última marca de tiempo dentro.✓ Copiado

→ Inventario limitado en tiempo
Encuentra el cluster de errores

Busca en todos los archivos .log el patrón ERROR|FATAL|panic. Dame los 10 minutos con la mayor densidad de coincidencias.✓ Copiado

→ Ventana de tiempo reducida a minutos, no horas
Lee el contexto alrededor del primer fatal

Lee 50 líneas de contexto alrededor de la primera línea FATAL en app.log. Explica qué estaba haciendo el sistema justo antes de que se estrellara.✓ Copiado

→ Reconstrucción narrativa, no regurgitación de logs

Resultado: Una cronología de 5 oraciones que puedas pegar en el documento del incidente.

Errores comunes

Los archivos de log grandes (>50MB) agotan el contexto del modelo — Solicita solo extracción de head/tail + estilo grep; nunca pidas a Claude que 'lea el archivo completo' en nada grande

Combinar con: sentry · github

Haz preguntas sobre una carpeta de PDFs, Markdown y documentos

👤 Investigadores, analistas con un montón de material de referencia ⏱ ~15 min beginner

Cuándo usarlo: Tienes 50 documentos/contratos/reportes en una carpeta y necesitas extraer un hecho específico o comparar entre ellos.

Requisitos previos

Documentos organizados en una carpeta — Aplana a un directorio o un árbol poco profundo; Claude navega mejor en estructuras más planas

Flujo

Indexa la carpeta

Lista cada archivo bajo /research/2026-market-study/. Para cada uno, cuéntame el nombre de archivo y los primeros 200 caracteres.✓ Copiado

→ Inventario con vistas previas rápidas
Haz la pregunta real

¿Cuál de estos documentos menciona 'tope de indemnización contractual'? Para cada coincidencia, cita la oración exacta y dame el nombre del archivo.✓ Copiado

→ Citas con nombre de archivo, no solo impresiones
Síntesis entre documentos

Compara los topes de indemnización en los 3 documentos que los tienen. ¿Cuál es más favorable para nosotros y por qué?✓ Copiado

→ Comparación lado a lado con citas directas

Resultado: Respuestas con citas de nombre de archivo + comilla que puedas verificar en 30 segundos.

Errores comunes

Los PDFs escaneados son basados en imágenes — la búsqueda por contenido falla — Ejecuta OCR primero (p. ej. ocrmypdf) o usa un MCP PDF dedicado; anota los archivos 'no buscables' antes de comenzar
Claude resume y pierde la atribución de la fuente — Siempre requiere nombre de archivo + comilla exacta en el prompt; rechaza respuestas sin ella

Combinar con: memory

Crea un scaffold de un nuevo proyecto a partir de una especificación en un turno de chat

👤 Ingenieros que inician un nuevo servicio/lib/prototipo ⏱ ~10 min beginner

Cuándo usarlo: Tienes una especificación de un párrafo y quieres que el boilerplate (carpetas, package.json, README, tests) se materialice sin copiar de un repositorio de plantilla.

Requisitos previos

Directorio de destino vacío — mkdir /projects/newthing y apunta la raíz del filesystem a su padre

Flujo

Acuerda el diseño antes de escribir

Quiero una herramienta CLI de Node TypeScript que haga X. Propón la estructura de carpetas y lista cada archivo que crearías con un propósito de una línea. No escribas aún.✓ Copiado

→ Plan archivo por archivo — puedes vetar antes de tocar el disco
Escribe los archivos

Se ve bien. Crea todos esos archivos bajo /projects/newthing/. Usa contenido mínimo e idiomático — sin comentarios de marcador de posición, sin stubs 'TODO'.✓ Copiado

→ Archivos en disco, compila/lints limpio en el primer intento
Verifica leyendo de nuevo

Lee cada archivo que acabas de crear y confirma que el proyecto pasaría tsc --noEmit y npm test. Arregla cualquier cosa que no lo haría.✓ Copiado

→ Auto-verificación con arreglos concretos, no vaguedades

Resultado: Un proyecto skeleton funcionando en 3 minutos en lugar de 30.

Errores comunes

Claude escribe archivos y luego olvida lo que escribió a mitad de sesión — Haz que produzca el plan de archivo primero, luego escriba; releer al final detecta la divergencia

Combinar con: git · github

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

filesystem + github

Edita archivos localmente, empuja una rama y abre un PR sin salir del chat

Arregla el typo en src/utils/format.ts:42, luego empuja una nueva rama fix/typo-format y abre un PR titulado 'fix: typo in format.ts'.✓ Copiado

filesystem + git

Haz ediciones, revisa el diff, commaitea — todo dentro de Claude

Refactoriza los 3 helpers duplicados en src/ en un util compartido. Muéstrame el diff antes de commitear, luego commitea con un mensaje limpio.✓ Copiado

filesystem + sqlite

Lee un CSV del disco y cárgalo en una tabla SQLite para análisis

Lee /data/orders.csv, infiere tipos, y cárgalo en /data/analysis.db como tabla orders.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
read_text_file	path: str, head?: int, tail?: int	Lee un archivo de texto; usa head/tail para evitar cargar archivos enormes	free
read_media_file	path: str	Lee imágenes, PDFs, audio como base64 para entrada multimodal	free
read_multiple_files	paths: str[]	Lee archivos relacionados en lote en un turno (más rápido que N llamadas)	free
write_file	path: str, content: str	Crea un archivo nuevo o reemplaza uno completamente — destructivo	free
edit_file	path: str, edits: [{oldText, newText}], dryRun?: bool	Ediciones más seguras a nivel de línea; siempre prefiere sobre write_file para archivos existentes	free
create_directory	path: str	Crea un directorio (recursivo, estilo mkdir -p)	free
list_directory	path: str	ls no recursivo	free
directory_tree	path: str	Descripción general de una estructura de proyecto de un vistazo	free
move_file	source: str, destination: str	Renombra o relocaliza	free
search_files	path: str, pattern: str, excludePatterns?: str[]	Búsqueda de contenido recursiva — como grep	free
get_file_info	path: str	Stat de un archivo sin leer contenidos	free
list_allowed_directories	none	Confirma con cuáles raíces se inició el servidor	free

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: Ilimitado — es I/O local
Tokens por llamada: Depende del tamaño del archivo — presupuesta ~1 token por 4 caracteres de contenido de archivo
Monetario: Gratis
Consejo: Usa search_files y head/tail en lugar de leer archivos completos. Un log de 2MB volcado en contexto cuesta ~500k tokens.

Seguridad

Permisos, secretos, alcance

Ámbitos mínimos: filesystem-read filesystem-write (si muta)

Almacenamiento de credenciales: Sin credenciales — el acceso es a través de los directorios raíz pasados como argumentos

Salida de datos: Ninguno desde el servidor — el contenido de archivo se envía a tu proveedor de LLM a través del cliente MCP como contexto

No conceder nunca: root=/ root=$HOME root=/etc o /var

Nunca apuntes la raíz a / o $HOME — limita al directorio de proyecto único en el que estés trabajando.
Claude sobrescribirá sin preguntar. Commaitea a git antes de cualquier sesión de edición de múltiples archivos.

Resolución de problemas

Errores comunes y soluciones

Error: Path is not within allowed directories

El archivo está fuera de cada raíz pasada al inicio. Reinicia el servidor con un arg de raíz adicional, o usa list_allowed_directories para ver qué está realmente permitido.

Verificar: Pídele a Claude que llame a `list_allowed_directories`

ENOENT: no such file or directory

Typo de ruta o suposición de directorio de trabajo incorrecto. Usa directory_tree en la raíz para ver el diseño real.

edit_file: oldText not found

El patrón oldText debe coincidir exactamente incluyendo espacios en blanco. Pídele a Claude que primero ejecute read_text_file y copie la subcadena exacta.

Huge file freezes the client

No leas archivos completos más grandes que unos pocos MB. Usa parámetros head/tail en read_text_file, o search_files para encontrar solo las líneas relevantes.

Verificar: Primero verifica el tamaño del archivo con `get_file_info`

Alternativas

Filesystem vs otros

Alternativa	Cuándo usarla	Contrapartida
git MCP	Necesitas operaciones conscientes de versión (diff, blame, log) en lugar de I/O de archivo crudo	Sin herramientas de escritura; solo lectura a través de una lente de git
GitHub MCP	Los archivos residen en un repositorio remoto y no quieres un clon local	Requiere un PAT; la latencia por archivo es mucho mayor que el disco local
JetBrains MCP	Quieres que los cambios aparezcan en tu instancia IDE en ejecución con herramientas de refactor	Requiere un IDE JetBrains abierto; más pesado que el filesystem simple

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills