MCP Filesystem Server

:закладка: О нас

MCP Filesystem Server обеспечивает безопасный доступ к файловой системе для моделей ИИ через Model Context Protocol. Он обеспечивает строгую проверку пути и разрешает доступ только к предопределенным каталогам.

Related MCP server: MCP Filesystem Server

:компьютер: Технологии

• Машинопись

• Node.js

• MCP-SDK-комплект

• Зод

• Докер

• пнпм

:wrench: Инструменты

• Код Visual Studio

• ESLint

• Красивее

• Витест

• Docker-композитор

:пакет: Установка

:heavy_check_mark: Предварительные условия

Необходимо установить следующее программное обеспечение:

• Node.js (>=18.0.0)

• Гит

• пнпм (>=8.0.0)

• Докер (необязательно)

• Docker Compose (необязательно)

:arrow_down: Клонирование репозитория

  $ git clone https://github.com/gabrielmaialva33/mcp-filesystem.git
  $ cd mcp-filesystem

:arrow_forward: Запуск приложения

Местное развитие

  # Install dependencies
  $ pnpm install

  # Build the application
  $ pnpm build

  # Run the server (specify directory to allow access to)
  $ pnpm start /path/to/allowed/directory

  # Or use configuration file
  $ pnpm start --config=config.json

Использование пакета NPM

  # Install globally
  $ npm install -g @gabrielmaialva33/mcp-filesystem

  # Run the server
  $ mcp-filesystem /path/to/allowed/directory

  # Or use with npx (no installation needed)
  $ npx @gabrielmaialva33/mcp-filesystem /path/to/allowed/directory

  # Create a sample configuration file
  $ npx @gabrielmaialva33/mcp-filesystem --create-config=config.json

Использование Докера

  # Build the Docker image
  $ docker build -t gabrielmaialva33/mcp-filesystem .

  # Run using Docker
  $ docker run -i --rm -v /path/to/data:/data:ro gabrielmaialva33/mcp-filesystem /data

  # Use with config file
  $ docker run -i --rm -v /path/to/config.json:/app/config.json -v /path/to/data:/data gabrielmaialva33/mcp-filesystem --config=/app/config.json

Использование Docker Compose

  # Create a data directory
  $ mkdir -p data

  # Start the server
  $ docker-compose up -d

:gear: Использование

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

Claude Desktop можно настроить на использование этого сервера MCP для доступа к файловой системе. Добавьте следующее в ваш claude_desktop_config.json :

Использование локальной установки (рекомендуется)

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-filesystem",
      "args": [
        "/Users/gabrielmaia/Documents",
        "/Users/gabrielmaia/Desktop",
        "/Users/gabrielmaia/Downloads"
      ]
    }
  }
}

Обязательно сделайте исполняемый файл доступным глобально:

# Make the binary executable
chmod +x /Users/gabrielmaia/.nvm/versions/node/v22.14.0/bin/mcp-filesystem

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

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

Использование Докера

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

{
  "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",
        "gabrielmaialva33/mcp-filesystem",
        "/projects"
      ]
    }
  }
}

Доступные инструменты

Сервер файловой системы MCP предоставляет следующие инструменты:

Операции файловой системы

• read_file : Прочитать содержимое файла

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

• write_file : Создать или перезаписать файл

• edit_file : Вносите точные изменения с помощью предварительного просмотра различий

• create_directory : Рекурсивное создание каталогов

• list_directory : Список содержимого каталога

• directory_tree : Получить рекурсивное древовидное представление

• move_file : Переместить или переименовать файлы

• search_files : Поиск файлов, соответствующих шаблонам

• get_file_info : Получить метаданные файла

• list_allowed_directories : Просмотреть доступные каталоги

Системные и сетевые операции

• get_metrics : Просмотр показателей производительности сервера (v0.3.0+)

• execute_command : безопасное выполнение системных команд (v0.3.1+)

• curl_request : выполнение HTTP-запросов к внешним API (в версии 1.2.0)

Использование инструмента curl_request (в версии 1.2.0)

Инструмент curl_request позволит вам делать HTTP-запросы к внешним API:

// Example: Making a GET request with authentication
curl_request({
  url: 'https://api.example.com/data',
  method: 'GET',
  headers: {
    Authorization: 'Bearer your_token_here',
  },
})

// Example: POST request with JSON data
curl_request({
  url: 'https://api.example.com/create',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  data: '{"name":"Example","value":123}',
})

Более подробные примеры смотрите в файле docs/curl-tool-examples.md .

:sparkles: Особенности

Основные характеристики

• Безопасный доступ : строгая проверка пути предотвращает несанкционированный доступ.

• Операции с файлами : чтение, запись, редактирование и перемещение файлов.

• Операции с каталогами : создание, перечисление, получение древовидных представлений и поиск по каталогам.

• Доступ к метаданным : просмотр информации о файлах и каталогах

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

• Поддержка Docker : простое развертывание с Docker и Docker Compose

Новые возможности в v0.3.0

• Структурированное ведение журнала : подробное ведение журнала с различными уровнями (отладка, информация, предупреждение, ошибка)

• Показатели производительности : отслеживайте количество операций, ошибок и время выполнения.

• Управление конфигурацией : поддержка файлов конфигурации JSON

• Кэширование путей : улучшенная производительность для часто используемых путей.

• Улучшенная обработка ошибок : специализированные типы ошибок со структурированной информацией

• Проверка размера файла : предотвращение загрузки слишком больших файлов.

• Улучшения CLI : команды справки, информация о версии и генерация конфигурации

Параметры конфигурации

Вы можете создать файл конфигурации, используя:

$ mcp-filesystem --create-config=config.json

Пример конфигурации:

{
  "allowedDirectories": ["/path/to/allowed/dir1", "/path/to/allowed/dir2"],
  "logLevel": "info",
  "logFile": "/path/to/logs/mcp-filesystem.log",
  "serverName": "secure-filesystem-server",
  "serverVersion": "0.3.0",
  "cache": {
    "enabled": true,
    "maxSize": 1000,
    "ttlMs": 60000
  },
  "metrics": {
    "enabled": true,
    "reportIntervalMs": 60000
  },
  "security": {
    "maxFileSize": 10485760,
    "allowSymlinks": true,
    "validateRealPath": true
  }
}

:writing_hand: Автор

Лицензия

Лицензия Массачусетского технологического института