AI导哈

文件系统服务器

MCP文件系统服务器提供安全的文件访问、目录分析和系统资源监控功能，适用于需要远程文件管理和系统监控的场景。

  • by LyaKonch
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 LyaKonch/filesystem-mcp-server

使用说明

MCP Filesystem Server

Сервер файлової системи та моніторингу для Model Context Protocol (MCP). Надає безпечний доступ до файлів, аналіз директорій та моніторинг ресурсів системи.

Опис

Цей сервер реалізує MCP протокол для роботи з файловою системою та системою загалом:

  • 📂 Файлова система: Читання, запис, пошук, безпечне видалення файлів.
  • 🛡️ Безпека: Аналіз директорій на вразливості та "сміття" (analyze_directory_security).
  • 📊 Моніторинг: Перегляд використання CPU, RAM, дисків та інформації про систему.
  • ⚙️ Керування: Динамічне додавання/видалення дозволених директорій під час роботи.

Встановлення

Передумови

  • Python 3.11+
  • uv (рекомендовано) або pip

Швидкий старт (uv)

# Клонуйте репозиторій
git clone <repository-url>
cd filesystem-mcp-server

# Встановіть залежності
uv sync

# Запустіть (без аутентифікації для локального використання)
python main.py --allow-cwd --no-auth

Використання та аргументи

Основні параметри запуску

Сервер підтримує гнучкі налаштування через аргументи командного рядка:

Аргумент Опис
roots Шляхи до дозволених директорій (наприклад python main.py /path/to/dir).
--allow-cwd Дозволити доступ до поточної робочої директорії.
--no-auth Рекомендовано. Вимикає аутентифікацію (корисно, якщо виникають помилки з токенами).
--transport Тип транспорту: stdio (за замовчуванням), http або sse.
--host, --port Хост та порт для HTTP/SSE (за замовчуванням 127.0.0.1:8000).
--persist Зберігати стан сервера (дозволені клієнти) між перезапусками.
--debug Увімкнути детальне логування для розробки.

Приклади запуску

  1. Локальний режим через STDIO (для Claude Desktop)
python main.py --allow-cwd --no-auth
  1. HTTP Server (для віддалених підключень)
python main.py --transport http --host 127.0.0.1 --port 8000 --persist

Доступні інструменти (Tools)

📁 Розширена робота з файлами

  • list_files(path) - Перегляд вмісту.
  • list_directory_with_sizes(path) - Список файлів з їх розмірами.
  • read_file(path) / read_multiple_files(paths) - Читання одного або кількох файлів.
  • write_file(path, content) - Створення або перезапис файлу.
  • move_file(source, dest) - Переміщення/перейменування.
  • delete_file(path, confirm) - Видалення файлу. Вимагає підтвердження (confirm=True або через діалог з користувачем).
  • delete_directory(path, confirm) - Рекурсивне видалення папки.
  • search_files(path, pattern) - Пошук за glob-шаблонами.
  • filesystem_summary(path) - Звіт про кількість файлів та загальний розмір.

🛡️ Аналіз та AI

  • analyze_directory_security(path) - Сканує папку на підозрілі файли, дублі, великі файли та оцінює безпеку. Може використовувати AI для звіту.
  • get_creative_file_description(path) - Використовує AI для опису вмісту файлу (якщо клієнт підтримує sampling).

📊 Моніторинг системи

  • get_system_resource_usage() - Завантаження CPU та RAM у реальному часі.
  • get_disk_status() - Інформація про вільне місце на всіх дисках.
  • get_system_info() - Деталі про OS, аптайм, версію ядра та хостнейм.

⚙️ Керування сервером

  • get_server_status() - Перевірка активного транспорту, features клієнта та поточних roots.
  • list_allowed_roots() - Показати всі доступні папки.
  • add_allowed_root(path) - Додати нову папку в білий список без перезапуску сервера.
  • remove_root(path) - Забрати доступ до папки.

Налаштування MCP Клієнта (Claude Desktop / Cursor)

Рекомендована конфігурація (STDIO)

Найпростіший спосіб без проблем з портами та токенами.

{
  "mcpServers": {
    "filesystem": {
      "command": "python",
      "args": [
        "absolute/path/to/main.py",
        "--allow-cwd",
        "--no-auth"
      ]
    }
  }
}

Не забудьте вказати повний шлях до python (наприклад .venv/Scripts/python), якщо використовуєте віртуальне середовище.

Конфігурація через HTTP (SSE)

Якщо ви запускаєте сервер окремо (python main.py --transport http --port 8000 --persist).

{
  "mcpServers": {
    "filesystem-http": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8000/mcp"
      ]
    }
  }
}

Зверніть увагу на /mcp в кінці URL.

Налаштування авторизації (GitHub OAuth)

Для авторизації дивіться офіційний гайд: https://gofastmcp.com/integrations/github

Рекомендовано створити файл .env в корені сервера. config.py автоматично підтягне всі змінні.

Нюанси налаштування:

  • Потрібен GitHub OAuth App з коректним callback URL згідно гайду.
  • Заповніть FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID та FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET у .env.
  • Встановіть FASTMCP_SERVER_AUTH_GITHUB_BASE_URL на базовий URL сервера (для локального тесту зазвичай http://127.0.0.1:8000).
  • Для персистентної авторизації потрібні JWT_SIGNING_KEY та STORAGE_ENCRYPTION_KEY і запуск з --persist.
  • Якщо використовуєте Redis( не стабільне, не протестовано), задайте параметром --redis і задай REDIS_HOST/REDIS_PORT.
  • Для локального dev можна( і бажано ) запускати з --no-auth, якщо виникають помилки токенів.

Вирішення проблем

🔑 Проблеми з аутентифікацією (Invalid Token / Client Not Registered)

Якщо ви бачите помилки invalid_token або Client Not Registered:

  1. Зупиніть сервер.
  2. Запустіть його з прапорцем --no-auth.
  3. Оновіть конфіг клієнта, щоб він не очікував auth-flow.

Аутентифікація через GitHub зараз знаходиться в стадії активної розробки. Для стабільної роботи локально рекомендується її вимикати.

🌐 Помилка "Connection Refused" або 404

Переконайтеся, що ви вказуєте правильний порт і шлях. За замовчуванням сервер слухає порт 8000 і шлях /mcp.

  • Неправильно: http://127.0.0.1/
  • Правильно: http://127.0.0.1:8000/mcp

🔒 Access Denied / Path not allowed

Сервер дозволяє доступ тільки до тек, вказаних при запуску або доданих динамічно.

  • Використовуйте list_allowed_roots(), щоб побачити, куди є доступ.
  • Використовуйте add_allowed_root("/path/to/dir"), щоб надати доступ. } } }


### Перевірка конфігурації

Після налаштування mcp.json:

1. **Перезапустіть MCP клієнт** (Claude Desktop, Cursor тощо)
2. **Перевірте підключення:**
   - Використайте інструмент `get_client_features()` для перевірки можливостей
   - Викличте `get_allowed_roots()` для перевірки доступних директорій
3. **Протестуйте базові операції:**
   - `list_files(".")` - перегляд файлів
   - `read_file("README.md")` - читання файлу

### Налагодження конфігурації

#### Проблема: Сервер не запускається
**Рішення:**
- Перевірте правильність шляхів в `command` та `args`
- Переконайтеся, що Python та залежності встановлені
- Перевірте права доступу до файлів

#### Проблема: "No allowed roots specified"  
**Рішення:**
- Додайте директорії в `args` або використайте `--allow-cwd`
- Переконайтеся, що шляхи існують і доступні

#### Проблема: "Path is not within allowed roots"
**Рішення:**
- Перевірте список дозволених коренів через `get_allowed_roots()`
- Додайте необхідні директорії в конфігурацію


## Підтримка

Якщо у вас виникли питання або проблеми:
1. Перевірте розділ "Вирішення проблем" вище
2. Відвідайте [документацію FastMCP](https://gofastmcp.com) для детальної інформації
3. Створіть issue в репозиторії

---

**Примітка:** Цей сервер призначений для використання в безпечному середовищі. Завжди перевіряйте права доступу та обмежуйте доступ тільки до необхідних директорій.

相关 MCP