# Filesystem MCP: сервер для работы с файлами, запуск и инструменты

> Filesystem - эталонный MCP-сервер для работы с файлами в разрешённых каталогах. Пакет @modelcontextprotocol/server-filesystem, 14 инструментов, только stdio

Страница: https://mcpdoc.ru/servers/filesystem/
Указатель сайта: https://mcpdoc.ru/llms.txt

Filesystem читает и изменяет файлы только внутри каталогов, которые вы разрешили: аргументами запуска или через Roots клиента. В коде 14 инструментов; один из них, `read_file`, помечен устаревшим. Работает сервер только по stdio.

В июле 2025 года в нём исправили две уязвимости обхода проверки пути. Редакцию протокола сервер не заявляет.

сверено с первичными источниками 4 октября 2026

Сведения о сервере поддерживается эталонный сервер проекта MCP

- **Кто выпускает:** Проект Model Context Protocol

- **Сторона:** сам владелец продукта

- **Где работает:** локально

- **Пакет:** @modelcontextprotocol/server-filesystem (npm)

- **Версия:** 2026.8.31, 2026-08-31

- **Транспорты:** stdio

- **Редакция протокола:** не заявлена

- **Проверено:** 2026-10-04

- **Источник:** [github.com](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem)

## Для чего он нужен

[README сервера](https://github.com/modelcontextprotocol/servers/blob/5abed86c5317b833dd59907492d56c65981642aa/src/filesystem/README.md) называет его сервером на Node.js для действий с файловой системой: чтение и запись файлов, создание и просмотр каталогов, перемещение, поиск, сведения о файле.

Проект относит Filesystem к эталонным реализациям. По [корневому README](https://github.com/modelcontextprotocol/servers/blob/5abed86c5317b833dd59907492d56c65981642aa/README.md), это учебные примеры, а не готовые решения для промышленной эксплуатации, и разработчикам следует самим оценить требования к безопасности.

## Запуск

```json title="Настройка клиента: Filesystem с двумя разрешёнными каталогами"
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}
```

Пример взят из документации выпуска 2026.8.31 и здесь не запускался.

Каждый путь после имени пакета - разрешённый каталог. README описывает и запуск в Docker: каталоги подключаются внутрь `/projects`, а пометка `ro` делает каталог доступным только для чтения.

## Какие каталоги доступны

README описывает два способа задать разрешённые каталоги.

1. **Аргументы запуска.** Каталоги перечислены в команде.
2. **Roots.** Клиент, который поддерживает Roots, передаёт каталоги сам. README называет этот способ рекомендуемым: каталоги можно менять без перезапуска сервера, через уведомление `notifications/roots/list_changed`.

Три правила из README, на которые стоит обратить внимание:

- каталоги из Roots **полностью заменяют** каталоги из аргументов запуска;
- если сервер запущен без аргументов, а клиент не поддерживает Roots или прислал пустой список, сервер завершит инициализацию с ошибкой;
- сервер разрешает действия только внутри каталогов, заданных аргументами или через Roots.

## Инструменты

Имена сверены с [файлом `index.ts`](https://github.com/modelcontextprotocol/servers/blob/5abed86c5317b833dd59907492d56c65981642aa/src/filesystem/index.ts) и с опубликованным пакетом 2026.8.31: набор совпадает. Описания - по README.

| Инструмент | Что делает | Изменяет данные |
|---|---|---|
| `read_text_file` | читает файл как текст UTF-8; можно взять первые или последние N строк | нет |
| `read_file` | **устарел**; описание в коде: «DEPRECATED: Use read_text_file instead» | нет |
| `read_media_file` | возвращает файл в base64 с типом MIME; изображения и звук - как `image` и `audio` | нет |
| `read_multiple_files` | читает несколько файлов; неудача с одним не останавливает остальные | нет |
| `list_directory` | содержимое каталога с пометками `[FILE]` и `[DIR]` | нет |
| `list_directory_with_sizes` | то же с размерами файлов и итогом | нет |
| `directory_tree` | дерево каталога в JSON | нет |
| `search_files` | рекурсивный поиск по шаблону | нет |
| `get_file_info` | размер, время создания и изменения, тип, права | нет |
| `list_allowed_directories` | список каталогов, доступных серверу | нет |
| `create_directory` | создаёт каталог вместе с родительскими; если каталог есть - ничего не делает | да |
| `write_file` | создаёт файл или перезаписывает существующий | да |
| `edit_file` | точечные правки по образцу текста; есть пробный режим `dryRun` | да |
| `move_file` | перемещает или переименовывает; не срабатывает, если цель существует | да |

В README инструмента `read_file` уже нет, но в коде он зарегистрирован под заголовком «Read File (Deprecated)». Клиент увидит его в списке. Для чтения текста используйте `read_text_file`.

Ресурсов и промптов сервер не объявляет.

## Аннотации инструментов

README сообщает, что сервер ставит на каждый инструмент аннотации: `readOnlyHint`, `idempotentHint`, `destructiveHint`. Все инструменты получают `openWorldHint: false` - сервер работает только с локальными файлами.

| Инструмент | `readOnlyHint` | `idempotentHint` | `destructiveHint` |
|---|---|---|---|
| девять инструментов чтения (все из таблицы выше, кроме `read_file`: в таблице README его нет) | `true` | - | - |
| `create_directory` | `false` | `true` | `false` |
| `write_file` | `false` | `true` | `true` |
| `edit_file` | `false` | `false` | `true` |
| `move_file` | `false` | `false` | `true` |

Аннотации - подсказки, а не защита. Спецификация требует: клиент обязан считать аннотации инструментов недоверенными, если они получены не от доверенного сервера ([раздел Tools](https://modelcontextprotocol.io/specification/2026-07-28/server/tools)).

## Транспорт

Только stdio: в исходном коде используется один транспорт `StdioServerTransport`.

## Безопасность

### Исправленные уязвимости

| Номер | Суть | Затронуты версии | Исправлено в |
|---|---|---|---|
| [CVE-2025-53109](https://github.com/advisories/GHSA-q66q-fx2p-7w4m) | обход проверки пути через сравнение по началу строки и символические ссылки | `0.6.2` и ниже; от `2025.1.14` до `2025.7.1` | `2025.7.1` |
| [CVE-2025-53110](https://github.com/advisories/GHSA-hc55-p739-j48w) | обход проверки пути через каталог с совпадающим началом имени | `0.6.2` и ниже; от `2025.1.14` до `2025.7.1` | `2025.7.1` |

Обе записи опубликованы 1 июля 2025 года с уровнем «высокий». В README сервера они не упомянуты, поэтому проверять установленную версию приходится самому: исправление вошло в `2025.7.1`, версии из указанных диапазонов ниже неё затронуты.

### Что делает сам сервер

- Перед действием путь приводится к настоящему (через `realpath`), и символическая ссылка, ведущая за пределы разрешённых каталогов, отклоняется - это видно в [файле `lib.ts`](https://github.com/modelcontextprotocol/servers/blob/5abed86c5317b833dd59907492d56c65981642aa/src/filesystem/lib.ts).
- README просит осторожности с `write_file` и советует сначала вызывать `edit_file` в режиме `dryRun`.

### Что остаётся за вами

Сервер получает столько, сколько вы ему разрешили. Разрешённый домашний каталог целиком - это и ключи, и настройки программ. Давайте самый узкий каталог, а для чтения - подключение только на чтение. Ограничения на уровне операционной системы и контейнера - практика, не правило MCP.

## Редакция протокола

Сервер не заявляет, по какой редакции протокола он работает. В README есть одна ссылка на страницу спецификации редакции `2025-03-26` - там, где объясняются аннотации инструментов. Ссылка на документ - не заявление о поддержке.

В зависимостях опубликованного пакета 2026.8.31 стоит `@modelcontextprotocol/sdk ^1.30.0`. Это факт о пакете. Вывода о редакции протокола из него этот сайт не делает.

## Что читать дальше

- [Эталонные серверы](https://mcpdoc.ru/servers/overview/) - все семь серверов.
- [Инциденты](https://mcpdoc.ru/security/incidents/) - разбор известных уязвимостей в серверах и клиентах.
- [Tools](https://mcpdoc.ru/protocol/tools/) - как устроены инструменты и их аннотации.
- [Как выбрать и проверить сервер](https://mcpdoc.ru/servers/choose/) - порядок проверки перед подключением.