mcp-filesystem

Усиленный файловый MCP-сервер. Даёт локальной модели доступ на чтение и запись к набору выбранных вами каталогов — и ни к чему больше.

Построен на MCP TypeScript SDK v2 для ревизии протокола 2026-07-28, с обратной совместимостью для клиентов 2025 года на той же конечной точке. Работает через stdio (для LM Studio, Claude Desktop и всего остального, что запускает локальный процесс) или Streamable HTTP (для контейнеризированной общей конечной точки).

Почему именно этот

Большинство файловых MCP-серверов проверяют, что путь начинается с разрешённого префикса, и на этом останавливаются. Это упускает три важные вещи:

• Символические ссылки. Ссылка, размещённая внутри песочницы и указывающая на /etc, полностью обходит проверку префикса.

• Запись через каталоги-симлинки. realpath выбрасывает исключение для путей, которых ещё не существует, поэтому серверы, которые разрешают только существующие файлы, с радостью создадут sandbox/linkdir/payload.sh за пределами песочницы.

• Коллизии префиксов. /data-secrets начинается с /data.

Этот сервер разрешает каждый путь до его физического расположения перед принятием решения — поднимаясь до самого глубокого существующего предка, если целевой путь ещё не существует — и сравнивает с realpath-корнями с учётом разделителей. Тестовый набор проверяет, что каждый из этих обходов не срабатывает.

Related MCP server: MCP Filesystem Server

Инструменты

Записи атомарны: содержимое помещается во временный файл в том же каталоге, выполняется fsync, затем переименовывается поверх целевого. Сбой или заполненный диск оставляют оригинал нетронутым, а не обрезанным.

Быстрый старт

npm install
npm run build
npm test

Затем укажите клиенту на него:

node dist/index.js --root ./workspace

Или попробуйте интерактивно без настройки клиента:

npx @modelcontextprotocol/inspector node dist/index.js --root ./workspace

LM Studio

LM Studio читает ~/.lmstudio/mcp.json (на Windows — C:\Users\<you>\.lmstudio\mcp.json). Откройте его через Program → Install → Edit mcp.json, добавьте запись в mcpServers, затем перезагрузите LM Studio.

Запуск нативно

Самый простой вариант, с которого стоит начать.

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-file-system/dist/index.js",
        "--root", "/absolute/path/to/your/project",
        "--read-only"
      ]
    }
  }
}

Уберите --read-only, когда доверяете серверу. Добавьте больше флагов --root для дополнительных каталогов.

Эти два пути должны быть абсолютными. Хост запускает сервер как дочерний процесс с непредсказуемой рабочей директорией, поэтому относительный путь не разрешится. В командной строке, где вы контролируете рабочую директорию, относительные пути, такие как --root ./workspace, допустимы.

На Windows пишите либо с прямыми слэшами (C:/Users/you/projects), либо удваивайте обратные слэши, так как одиночный \ является escape-символом внутри JSON-строки.

Запуск в Docker

Docker даёт границу, обеспечиваемую ядром, под собственными проверками сервера — это и есть главный аргумент: даже ошибка в коде песочницы не сможет добраться до того, что вы не смонтировали.

docker build -t mcp-filesystem:latest .

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "--network", "none",
        "-v", "/absolute/path/to/your/project:/data:ro",
        "mcp-filesystem:latest",
        "--stdio", "--read-only"
      ]
    }
  }
}

Примечания:

• -i обязателен. Без него контейнер не получает stdin, и рукопожатие JSON-RPC не происходит — это самая распространённая ошибка конфигурации.

• --network none стоит установить: этому серверу нет причин выходить в сеть, а удаление интерфейса устраняет целый класс утечек.

• :ro на монтировании делает ограничение на запись задачей ядра. Чтобы разрешить запись, уберите :ro и уберите --read-only.

• Docker требует, чтобы сторона хоста в -v была абсолютным путём.

• В Docker Desktop для Windows диск, с которого вы монтируете, должен быть доступен через Settings → Resources → File sharing.

• На Linux-хосте добавьте --user "$(id -u):$(id -g)", чтобы записанные файлы принадлежали вам, а не uid 1000.

Смонтируйте несколько каталогов, повторяя -v и передавая соответствующие флаги --root:

"-v", "/absolute/path/to/your/code:/data/code:ro",
"-v", "/absolute/path/to/your/notes:/data/notes",
"mcp-filesystem:latest",
"--stdio", "--root", "/data/code", "--root", "/data/notes"

HTTP-транспорт

Для долгоживущего контейнера, который используют несколько клиентов:

docker compose up -d
curl http://127.0.0.1:3000/health

Укажите клиенту на http://127.0.0.1:3000/.

У этого сервера нет аутентификации. Любой, кто может добраться до порта, получает тот же доступ к файловой системе, что и сервер. docker-compose.yml публикует только на 127.0.0.1. Если вы привязываете его к другому адресу, поставьте перед ним аутентифицирующий обратный прокси и ожидайте предупреждения в журнале запуска.

При привязке к loopback сервер проверяет заголовки Host и Origin, чтобы блокировать DNS-rebinding — когда посещённая вами веб-страница разрешает управляемый атакующим домен в 127.0.0.1 и отправляет POST на этот порт.

Конфигурация

У каждого флага есть эквивалент в виде переменной окружения, который использует контейнер. Флаги командной строки имеют приоритет.

Сервер отказывается запускаться без настроенных корней. Файловый сервер без песочницы — небезопасное значение по умолчанию, а установка рабочей директории по умолчанию лишь делает ошибку незаметной.

Список запретов по умолчанию

Заблокировано, если не передать --allow-default-denied: .env и .env.*, *.pem, *.key, *.p12, *.pfx, *.keystore, id_rsa/id_dsa/id_ecdsa/id_ed25519, .ssh/, .aws/, .gnupg/, .kube/config, .npmrc, .netrc, .pypirc, .docker/config.json, .git/, .svn/, .hg/, shadow.

Это существует, чтобы неосторожный -v $HOME:/data был переживаемым. Это страховочная сеть, а не замена монтированию правильного каталога.

Модель безопасности

Что обеспечивается

• Физическое разрешение пути (realpath) перед каждым решением о границах, включая пути, которых ещё нет

• Сопоставление корней с учётом разделителей (/data никогда не совпадает с /data-secrets)

• Симлинки отклоняются по умолчанию в любой позиции пути — не только в конечном элементе

• Отклонение NUL-байтов (safe.txt\0/../../etc/passwd обрезается в системном вызове)

• Windows: альтернативные потоки данных (file:stream), зарезервированные имена устройств (CON, NUL, COM1…), пути в пространстве имён устройств (\\?\, \\.\) и проверка границ без учёта регистра

• Режим только для чтения блокирует изменяющие инструменты до выполнения обработчика

• Оба операнда проверяются при move/copy — проверка только источника является примитивом записи для всего хоста

• Разрешённые корни нельзя удалить или переместить

• Лимиты размера проверяются через stat до выделения

• Определение бинарных файлов, чтобы бинарники не возвращались как мусор, сжигающий токены

• Регулярные выражения проверяются, и для grep_files установлен крайний срок по настенным часам

• Сообщения об ошибках никогда не повторяют пути хоста; SecurityError возвращает модели расплывчатое сообщение и записывает реальную причину в поток аудита, чтобы песочница не была оракулом для картирования вашей файловой системы

Что не обеспечивается

• TOCTOU. Между разрешением пути и его открытием локальный атакующий, имеющий право записи внутри ваших разрешённых корней, может подменить файл на симлинк. Для закрытия этой дыры нужен openat2(RESOLVE_BENEATH) на Linux, который Node не предоставляет. Практическое смягчение — граница контейнера: монтируйте только то, что намерены открыть.

• Аутентификация. Ни один транспорт не аутентифицирует. stdio наследует доверие того, кто запустил процесс; HTTP — только loopback по этой причине.

• Истощение ресурсов. Лимиты и крайние сроки ограничивают большинство вещей, но патологическое регулярное выражение всё ещё может сжечь один 15-секундный крайний срок CPU. Файл compose устанавливает лимиты памяти и CPU.

• Инъекция подсказок. Если файл внутри вашей песочницы содержит инструкции и ваша модель им следует, этот сервер будет добросовестно выполнять любые инструменты, которые модель вызовет дальше. Режим только для чтения — это смягчение, которое действительно работает.

Укрепление контейнера (в docker-compose.yml): пользователь без прав root, read_only корневая файловая система, все capabilities отозваны, no-new-privileges, tmpfs /tmp, лимиты памяти и CPU.

Журнал аудита

Один JSON-объект на строку в stderr — никогда в stdout, который является каналом JSON-RPC при stdio. console.log перехватывается и перенаправляется в stderr при запуске, чтобы случайный оператор отладки не повредил поток протокола.

{"ts":"2026-08-21T19:12:03.441Z","tool":"read_file","outcome":"ok","durationMs":3,"paths":["src/index.ts"],"bytes":4821}
{"ts":"2026-08-21T19:12:07.882Z","tool":"read_file","outcome":"denied","durationMs":1,"detail":"physical containment failed: /data/../etc/passwd -> /etc/passwd"}

Записанные пути относительны к песочнице. Поле detail содержит полную причину и записывается только здесь, никогда не возвращается модели.

docker compose logs -f filesystem | jq 'select(.outcome=="denied")'

Тесты

npm run build && npm test

test/sandbox.test.ts — это набор, который имеет значение: каждый случай — попытка добраться до файла за пределами корня. Если один из них начнёт проходить там, где должен выбрасывать исключение, сервер сломан единственным по-настоящему опасным образом.

Тесты симлинков пропускают себя на Windows, если не включён режим разработчика, поскольку создание симлинков в противном случае требует прав администратора.

Структура проекта

src/
  index.ts              entrypoint, transport selection, shutdown
  config.ts             CLI + env parsing, root resolution
  security/
    sandbox.ts          path resolution and containment — the security core
    audit.ts            structured stderr logging, stdout protection
  tools/
    context.ts          registration wrapper: read-only gate, errors, audit
    read.ts             read_file, read_multiple_files, get_file_info, ...
    write.ts            write_file, append_file, edit_file
    listing.ts          list_directory, directory_tree
    manage.ts           create_directory, move_file, copy_file, delete_file
    search.ts           search_files, grep_files
  util/
    walk.ts             sandbox-aware directory traversal with cycle guard
    binary.ts           binary detection, BOM handling
    errors.ts           error taxonomy and fs error translation
    format.ts           output formatting for model consumption

Лицензия

MIT