Файловый MCP-сервер

Сервер Node.js, реализующий Протокол контекста модели (MCP) для операций с файловой системой.

Опубликован в npm как @modelcontextprotocol/server-filesystem.

Возможности

• Чтение/запись файлов

• Создание/просмотр/удаление директорий

• Перемещение файлов/директорий

• Поиск файлов

• Получение метаданных файлов

• Динамический контроль доступа к директориям через Корни (Roots)

Контроль доступа к директориям

Сервер использует гибкую систему контроля доступа к директориям. Директории могут быть указаны через аргументы командной строки или динамически через Корни (Roots).

Способ 1: Аргументы командной строки

Укажите разрешённые директории при запуске сервера:

mcp-server-filesystem /path/to/dir1 /path/to/dir2

Способ 2: MCP Корни (рекомендуется)

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

Корни, отправленные клиентом серверу, полностью заменяют любые разрешённые директории на стороне сервера при их предоставлении.

Важно: Если сервер запускается без аргументов командной строки И клиент не поддерживает протокол корней (или предоставляет пустые корни), сервер выдаст ошибку во время инициализации.

Это рекомендуемый способ, так как он позволяет обновлять директории во время выполнения через уведомления roots/list_changed без перезапуска сервера, обеспечивая более гибкий и современный опыт интеграции.

Как это работает

Управление доступом к директориям сервера выполняется по следующему алгоритму:

1. Запуск сервера

   • Сервер запускается с директориями из аргументов командной строки (если они указаны)

   • Если аргументы не указаны, сервер запускается с пустым списком разрешённых директорий

2. Подключение клиента и инициализация

   • Клиент подключается и отправляет запрос initialize с возможностями

   • Сервер проверяет, поддерживает ли клиент протокол корней (capabilities.roots)

3. Обработка протокола корней (если клиент поддерживает корни)

   • При инициализации: Сервер запрашивает корни у клиента через roots/list

   • Клиент отвечает своими настроенными корнями

   • Сервер заменяет ВСЕ разрешённые директории корнями клиента

   • При обновлениях во время выполнения: Клиент может отправлять уведомления notifications/roots/list_changed

   • Сервер запрашивает обновлённые корни и снова заменяет разрешённые директории

4. Поведение по умолчанию (если клиент не поддерживает корни)

   • Сервер продолжает использовать только директории из командной строки

   • Динамические обновления невозможны

5. Контроль доступа

   • Все операции с файловой системой ограничены разрешёнными директориями

   • Используйте инструмент list_allowed_directories для просмотра текущих директорий

   • Сервер требует минимум ОДНУ разрешённую директорию для работы

Примечание: Сервер будет разрешать операции только в директориях, указанных либо через args, либо через Корни.

API

Инструменты

• read_text_file

  • Чтение полного содержимого файла как текста

  • Входные данные:

    • path (строка)

    • head (число, необязательно): Первые N строк

    • tail (число, необязательно): Последние N строк

  • Всегда обрабатывает файл как текст в кодировке UTF-8 независмо от расщирения

  • Нельзя указать одновремено и head, и tail

• read_media_file

  • Чтение файла и возврат его как блока содержимого в кодировке base64 с указанием MIME-типа

  • Входные данные:

    • path (строка)

  • Потоковая передача файла и возврат данных base64 с соотвествущим MIME-типом. Файлы изображенй и аудио возвращаются как содержимое image/audio; любой другой тип файла возвращается как встроенный resource (допустимый блок содержимого MCP для произвольных двоичных данных)

• read_multiple_files

  • Чтение нескольких файлов одновремено

  • Вход: paths (строка[])

  • Неудачные чтения не останавливают всю операцию

• write_file

  • Создание нового файла или перезапись существующего (соблюдайте осторожность)

  • Входные данные:

    • path (строка): Распложение файла

    • content (строка): Содержимое файла

• edit_file

  • Выборочное редактирование с использованием расширеного сопоставления шаблонов и форматирования

  • Возможности:

    • Сопоставление содержимого по строкам и нескольким строкам

    • Нормализация пробелов с сохранением отступов

    • Несколько одновременых правок с правильным позиционированием

    • Определение и сохранение стиля отступов

    • Вывод различий в стиле Git с контекстом

    • Предварительный просмотр изменений в режиме «сухого прогона»

  • Входные данные:

    • path (строка): Файл для редактирования

    • edits (массив): Список операци правки

      • oldText (строка): Текст для поиска (может быть подстрокой)

      • newText (строка): Текст для замены

    • dryRun (булево): Предварительный просмотр изменений без применения (по умолчанию: false)

  • Возвращает подробные различия и информацию о сопоставлении для сухих прогонов, иначе применяет изменения

  • Рекомендуем: Всегда сначала используйте dryRun для просмотра изменений перед их применинием

• create_directory * Создание новой диретории или подверждение еёсуществования

  • Вход: path (строка)

  • Создаёт родительские диретории ри неободимости

  • Завершается успешно без сообщения, если диретория уже сущестует

• list_directory

  • Просмотр содеримого диретории с префиксами [FILE] или [DIR]

  • Вход: path (сторка)

• list_directory_with_sizes

  • Просмотр содеримого диретории с префиксами [FILE] или [DIR], включая разеры файлов

  • Входные данные:

    • path (сторка): путь к диретории для просмотра

    • sortBy (сторка, необязательно): Сортировать записи по "name" или "size" (по умолчанию: "name")

  • Возвращает одробный список с рамерами файлов и итоговои статистикой

  • Показывает общее количество файлов, директорий и общий размер

• move_file

  • Перемещение или переименование файлов и директорий

  • Входные данные:

    • source (сторка)

    • destination (сторка)

  • Завершается неудачей, ели целевой путь уже сушествует

• search_files

  • Рекурсивный посик файлов/директорий, которые соответтвуют или не соответтвуют шаблонам

  • Входные данные:

    • path (сторка): Начальная диретория

    • pattern (сторка): Шаблон поска

    • excludePatterns (сторка[]): Исключить любые абоны.

  • Сопоставление шаблонов в стиле Glob

  • Возвращает полные пути к совпадениям

• directory_tree

  • Получение рекурсивной JSON-структуры дерева содержимого диретории

  • Входные данные:

    • path (сторка): Начальная диретория

    • excludePatterns (сторка[]): Исключить любые абоны. Поддерживаются форматы Glob.

  • Возвращает:

    • JSON-массив, где каждая запись содержит:

      • name (сторка): Имя файла/директории

      • type ('file'|'directory'): Тип записи

      • children (массив): Присутствует только для директорий

        • Пустой массив для пустых директорий

        • Опущен для файлов

  • Вывод форматируется с отступом в 2 пробела для удобства чтения

• get_file_info

  • Получение подробных метаданных файла/директории

  • Вход: path (строка)

  • Возвращает:

    • Размер

    • Время создания

    • Время изменения

    • Время доступа

    • Тип (файл/директория)

    • Права доступа

• list_allowed_directories

  • Просмотр всех директорий, к которым серверу разрешён доступ

  • Входные данные не требуются

  • Возвращает:

    • Директории, из которых этот сервер может читать/записывать

Аннотации инструментов (подсказки MCP)

Этот сервер устанавливает MCP ToolAnnotations на каждый инструмент, чтобы клиенты могли:

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

• Понимать, какие оперции записи являются идепотентными (безопасными для повтора с теми же аргументами).

• Выделять оперции, которые могут быть разрушительными (перезапись или сильное изенение данных).

• Указывать, что интрумент не обращается к открытому или внешнему миру (каждый файловый инструмент устанавливает openWorldHint: false).

Соответствие для файловых интрументов:

Примечание: idempotentHint и destructiveHint имеют смысл только тогда, когда readOnlyHint равен false, как определено спецификацией MCP. Каждый инструмент также устанавливает openWorldHint: false — этот сервер обращается только к локальной файловой системе в прелелах своих разрешённых директорий, никогда к открытому или внешнему мире.

Использование с Claude Desktop

Добавьте это в ваш claude_desktop_confg.jon:n nПримечание: вы можете предоставить изолированные директории серверу, смонтировав их в /projects. Добавление флага ro сделает директорию доступной только для чтения сервером.

Docker

Примечание: все директории должы быть смонтированы в /projects по умолчанию.

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

В Windows используйте cmd /c для запуска npx:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

Использование с VS Code

Для быстрой установки нажмите кнопки установки ниже...

Для ручной устаовки вы можете настроить MCP-сервер, используя один из этих спосоов:

Метод 1: Конфигурация пользователя (рекомендуется) Добавьте конфигурацию в файл конфигурации MCP на уровне пользователя. Откройте палитру команд (Ctrl + Shift + P) и выполните MCP: Open User Configuration. Это откроет ваш пользовательский файл mcp.json, в который вы можете добавить конфигурацию сервера.

Метод 2: Конфигурация рабочей области В качестве альтернативы вы можете добавить конфигурацию в файл .vscode/mcp.json в вашей рабочей области. Это позволит вам делиться конфигурацией с другими.

Для получения дополнительных сведений о конфигурации MCP в VS Code обратитесь к официальной документации VS Code по MCP.

Вы можете предоставить серверу изолированные каталоги, смонтировав их в /projects. Добавление флага ro сделает каталог доступным только для чтения для сервера.

Docker

Примечание: все каталоги должны быть смонтированы в /projects по умолчанию.

{
  "servers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

В Windows используйте:

{
  "servers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

Сборка

Сборка Docker:

docker build -t mcp/filesystem -f src/filesystem/Dockerfile .

Лицензия

Этот MCP-сервер лицензируется в соответствии с лицензией MIT. Это означает, что вы можете свободно использовать, изменять и распространять программное обеспечение при соблюдении условий лицензии MIT. Для получения дополнительных сведений обратитесь к файлу LICENSE в репозитории проекта.