Filesystem MCP — сервер, который открывает AI-агенту прямой доступ к локальным файлам. С его помощью Claude Desktop, продолжение Claude Code и другие совместимые клиенты могут читать, создавать, изменять и удалять файлы на вашем компьютере. Это превращает языковую модель из просто чата в инструмент, способный работать с реальными проектами.
Но с этим доступом приходит и ответственность. Неправильная настройка может открыть системе доступ к конфиденциальным данным — паролям, SSH-ключам, переменным окружения. В этой статье разберём, как настроить filesystem MCP безопасно, какие директории стоит открывать, а какие — категорически нет, и как проверить, что конфигурация работает корректно.
Что такое Filesystem MCP и зачем он нужен
Model Context Protocol (MCP) — открытый стандарт, который позволяет AI-моделям взаимодействовать с внешними инструментами и данными. Спецификация версии 2025-03-26 определяет, как клиент (например, Claude Desktop) общается с сервером, предоставляющим ресурсы, промпты и инструменты.
Filesystem MCP — один из референсных серверов в официальном репозитории modelcontextprotocol/servers. Он предоставляет набор инструментов для работы с файловой системой: чтение файлов, запись, создание директорий, поиск, получение метаданных. В отличие от обычного copy-paste в чат, этот сервер позволяет модели напрямую оперировать файлами в указанных директориях.
Основные сценарии использования:
— Редактирование конфигурационных файлов проекта
— Создание и обновление документации
— Пакетная обработка текстовых файлов
— Автоматизация рутинных операций с файловой структурой
— Интеграция с системами контроля версий через чтение файлов проекта
Как установить и настроить Filesystem MCP
Установка сервера требует Node.js (версия 18 или выше). Сервер распространяется через npm как часть пакета @modelcontextprotocol/server-filesystem.
Установка глобально:npm install -g @modelcontextprotocol/server-filesystem
После установки сервер нужно зарегистрировать в конфигурации клиента. Для Claude Desktop на macOS файл конфигурации находится по пути:~/Library/Application Support/Claude/claude_desktop_config.json
Пример минимальной конфигурации:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/projects"
]
}
}
}
Аргумент после имени пакета — это путь к директории, к которой сервер получает доступ. Можно указать несколько директорий через пробел:
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/projects",
"/Users/username/documents"
]
Какие директории безопасно открывать
Выбор директорий — ключевой момент настройки. Сервер получает доступ только к тем путям, которые явно указаны в конфигурации, но в пределах этих путей он может выполнять любые файловые операции.
Безопасные варианты:
— ~/projects или ~/dev — изолированная рабочая директория
— ~/documents/ai-work — отдельная папка для работы с AI
— Временные директории, созданные специально для агента
Что не стоит открывать:
— ~/.ssh — приватные ключи
— ~/.config — конфигурационные файлы приложений
— ~/.aws или ~/.azure — credentials облачных провайдеров
— /etc или /usr — системные директории
— ~/.git-credentials и аналогичные файлы с паролями
Хорошая практика — создать отдельную директорию для работы AI-агента и копировать в неё только те файлы, с которыми модель должна работать. Это имитация sandbox-режима, который пока не реализован на уровне самого сервера.
Проверка работы сервера и отладка
После настройки конфигурации перезапустите Claude Desktop. В интерфейсе появится новый инструмент — иконка молотка или список доступных MCP-инструментов.
Чтобы проверить, что сервер работает корректно, можно задать простой запрос:
«Прочитай файл README.md в директории projects и кратко опиши его содержание»
Если сервер настроен правильно, модель запросит разрешение на чтение файла и выполнит операцию.
Логи MCP-серверов в Claude Desktop можно посмотреть через меню: Help → View Logs. Ошибки подключения или неверные пути отображаются там.
Для диагностики можно запустить сервер вручную из терминала:npx @modelcontextprotocol/server-filesystem /path/to/test
Сервер запустится и будет ожидать соединения по stdio. Если путь не существует или недоступен, сервер сообщит об ошибке.
Ограничения и риски, которые нужно знать
Filesystem MCP — мощный, но небезопасный по умолчанию инструмент. Вот ключевые ограничения:
— Отсутствие sandbox-режима: сервер не изолирует операции от остальной системы. Если открыта директория ~/projects, сервер может удалить любой файл внутри неё.
— Символические ссылки: сервер следует по symlink’ам, если они ведут в разрешённую директорию. Но если symlink указывает за пределы разрешённой зоны, сервер блокирует операцию.
— Нет разграничения по операциям: сервер предоставляет все инструменты (чтение, запись, удаление) сразу. Нельзя открыть директорию только на чтение.
— Сетевые пути: сервер не предназначен для работы с сетевыми файловыми системами без дополнительной настройки.
На практике это означает, что filesystem MCP стоит использовать только в тех сценариях, где вы готовы доверить AI-агенту полный контроль над содержимым указанных директорий. Для работы с чувствительными данными лучше создать отдельную копию проекта.
Альтернативные подходы и сравнение
Если встроенный filesystem MCP кажется слишком рискованным, есть альтернативы:
| Подход | Уровень контроля | Сложность настройки |
|---|---|---|
| Filesystem MCP (стандартный) | Полный доступ к указанным директориям | Низкая |
| Кастомный MCP-сервер с whitelist операций | Ограниченный набор команд | Средняя |
| Docker-контейнер с MCP внутри | Изоляция на уровне ОС | Высокая |
| Использование только read-only операций | Только чтение | Средняя (требует модификации сервера) |
Кастомный сервер можно написать на Python или TypeScript, реализовав только нужные инструменты (например, только read_file и search_files, без write и delete). Это снижает риски, но требует дополнительных затрат на разработку.
Docker-изоляция — самый надёжный вариант для продакшен-сред: контейнер с MCP-сервером монтирует только нужную директорию и не имеет доступа к остальной системе.
Что делать прямо сейчас
Если вы планируете использовать filesystem MCP, начните с малого:
1. Установите сервер и настройте доступ к пустой тестовой директории
2. Проверьте, какие операции модель может выполнять
3. Создайте рабочую директорию для AI-агента и скопируйте туда только необходимые файлы
4. Регулярно проверяйте логи на предмет неожиданных операций
5. Для чувствительных проектов рассмотрите Docker-изоляцию или кастомный сервер
Официальная документация filesystem MCP-сервера доступна в репозитории modelcontextprotocol/servers. Спецификация MCP и примеры других серверов — на modelcontextprotocol.io. Если вы заметили необычное поведение или нашли баг, имеет смысл проверить актуальную версию пакета и issues на GitHub — сервер активно развивается, и ограничения, описанные в этой статье, могут быть сняты в будущих релизах.