@staminna/directus-mcp-server

MCP-сервер для Directus 12 — элементы, коллекции, файлы, потоки, пользователи и инструменты схемы. TypeScript, полностью типизирован.

Покрытие тестами

Бейджи покрытия генерируются из coverage/coverage-summary.json командой npm run badges (внешний сервис не требуется). Сначала выполните npm run test:coverage.

Возможности

• 🔐 Полная аутентификация — аутентификация на основе токена с Directus

• 📦 Управление коллекциями — операции CRUD для коллекций и элементов

• 📁 Файловые операции — загрузка, скачивание и управление файлами

• 🔄 Управление потоками — создание, обновление, запуск и управление потоками Directus

• 👥 Управление пользователями — CRUD пользователей и управление ролями

• 🔍 Инструменты схемы — анализ и проверка схем коллекций

• 🩺 Диагностика — диагностика доступа к коллекциям и устранение неполадок

Related MCP server: Storyblok MCP Server

Установка

Через npm (рекомендуется)

npm install -g @staminna/directus-mcp-server

Из исходного кода

git clone https://github.com/staminna/mcp-server-claude.git
cd mcp-server-claude
npm install
npm run build

Переменные окружения

TLS / клиентские сертификаты

Задайте эти переменные, когда экземпляр Directus использует частный центр сертификации (CA) или требует клиентский сертификат. Каждая из переменных CA/CERT/KEY/PFX принимает либо путь к файлу, либо само содержимое PEM/DER.

Аутентификация — OAuth не требуется

Этот сервер использует статический токен доступа Directus (DIRECTUS_TOKEN) и работает через stdio-транспорт. OAuth не требуется по замыслу:

• Спецификация MCP определяет авторизацию OAuth 2.1 только для транспортов на основе HTTP. Для stdio-серверов спецификация гласит, что реализации «SHOULD NOT» (не должны) использовать её и вместо этого должны получать учётные данные из окружения — именно так и поступает этот сервер.

• Directus 12 полностью поддерживает статические токены доступа. Поддержка OAuth 2.1, добавленная в Directus (в середине 2026 года), относится к его собственному встроенному удалённому MCP-эндпоинту и является опциональной; в Directus 12 нет ломающих изменений для аутентификации по токену (см. DIRECTUS_V12_BREAKING_CHANGES.md).

• OAuth становится актуальным, только если вы публикуете MCP-сервер удалённо через HTTP (Streamable HTTP/SSE). Будучи локальным stdio-подпроцессом Claude Desktop, Claude Code, Cursor и т.д., этот сервер требует только токен из окружения.

Создайте токен в Directus в разделе User Settings → Token (для продакшена используйте отдельного пользователя с ролью минимальных привилегий).

Использование с подпиской Claude (Max/Pro) — API-ключ не нужен

MCP-серверы сами по себе не расходуют токены Anthropic API; их расходуют только вызовы моделей AI-клиента. Если вы используете этот сервер в Claude Code или Claude Desktop с подпиской Claude Max (или Pro), использование моделей покрывается подпиской — вам не нужен ключ Anthropic API. Ключ API требуется только при программном использовании Claude через Claude API (например, удалённый MCP-коннектор).

Конфигурация IDE

🟣 Cursor

1. Откройте настройки Cursor: Cmd+, (macOS) или Ctrl+, (Windows/Linux)

2. Найдите «MCP» или перейдите в Features → MCP Servers

3. Нажмите «Edit in settings.json»

4. Добавьте следующую конфигурацию:

{
  "mcpServers": {
    "directus": {
      "command": "npx",
      "args": [
        "-y",
        "@staminna/directus-mcp-server"
      ],
      "env": {
        "DIRECTUS_URL": "http://localhost:8065",
        "DIRECTUS_TOKEN": "your-directus-token-here"
      }
    }
  }
}

Или, если установлено локально:

{
  "mcpServers": {
    "directus": {
      "command": "node",
      "args": [
        "/path/to/mcp-server-claude/dist/index.js"
      ],
      "env": {
        "DIRECTUS_URL": "http://localhost:8065",
        "DIRECTUS_TOKEN": "your-directus-token-here"
      }
    }
  }
}

5. Сохраните файл и перезапустите Cursor

🌊 Windsurf

1. Откройте настройки Windsurf: Cmd+, (macOS) или Ctrl+, (Windows/Linux)

2. Найдите «MCP Servers»

3. Нажмите «Edit in settings.json»

4. Добавьте следующую конфигурацию:

{
  "mcpServers": {
    "directus": {
      "command": "npx",
      "args": [
        "-y",
        "@staminna/directus-mcp-server"
      ],
      "env": {
        "DIRECTUS_URL": "http://localhost:8065",
        "DIRECTUS_TOKEN": "your-directus-token-here",
        "DIRECTUS_PROMPTS_COLLECTION_ENABLED": "true",
        "DIRECTUS_PROMPTS_COLLECTION": "ai_prompts",
        "DIRECTUS_RESOURCES_ENABLED": "true",
        "DIRECTUS_RESOURCES_EXCLUDE_SYSTEM": "true",
        "NODE_ENV": "production"
      }
    }
  }
}

Или, если установлено локально:

{
  "mcpServers": {
    "directus": {
      "command": "node",
      "args": [
        "/path/to/mcp-server-claude/dist/index.js"
      ],
      "env": {
        "DIRECTUS_URL": "http://localhost:8065",
        "DIRECTUS_TOKEN": "your-directus-token-here"
      }
    }
  }
}

5. Сохраните файл

6. Полностью закройте Windsurf (Cmd+Q или Ctrl+Q)

7. Снова откройте Windsurf и подождите ~10 секунд, пока MCP инициализируется

🤖 Claude Desktop

1. Найдите файл конфигурации Claude Desktop:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Создайте или отредактируйте файл конфигурации:

{
  "mcpServers": {
    "directus": {
      "command": "npx",
      "args": [
        "-y",
        "@staminna/directus-mcp-server"
      ],
      "env": {
        "DIRECTUS_URL": "http://localhost:8065",
        "DIRECTUS_TOKEN": "your-directus-token-here"
      }
    }
  }
}

Или, если установлено локально:

{
  "mcpServers": {
    "directus": {
      "command": "node",
      "args": [
        "/path/to/mcp-server-claude/dist/index.js"
      ],
      "env": {
        "DIRECTUS_URL": "http://localhost:8065",
        "DIRECTUS_TOKEN": "your-directus-token-here"
      }
    }
  }
}

3. Сохраните файл и перезапустите Claude Desktop

🔮 Claude.ai (веб-версия с MCP)

Для веб-интерфейса Claude.ai с поддержкой MCP:

1. Перейдите в настройки Claude.ai

2. Найдите раздел конфигурации MCP

3. Добавьте новый MCP-сервер со следующими настройками:

{
  "name": "directus",
  "command": "npx",
  "args": ["-y", "@staminna/directus-mcp-server"],
  "env": {
    "DIRECTUS_URL": "http://localhost:8065",
    "DIRECTUS_TOKEN": "your-directus-token-here"
  }
}

Примечание: поддержка MCP в Claude.ai может требовать подписки Pro и определённых расширений браузера.

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

Управление коллекциями

Схема и поля

Управление потоками

Управление пользователями

Управление файлами

Диагностика

Поиск

Аннотации безопасности инструментов

Каждый инструмент снабжён аннотациями MCP, чтобы клиент мог отличить операции чтения от операций записи до вызова: 17 имеют readOnlyHint: true, 6 явно имеют destructiveHint: false (аддитивные — создают), а 11 имеют destructiveHint: true (удаления, перезаписывающие обновления, apply_schema, import_data, trigger_flow).

Обратите внимание, что destructiveHint по умолчанию равен true в спецификации MCP, поэтому аддитивные инструменты устанавливают его в false, а не опускают.

Безопасное удаление элементов

Начиная с Directus 12.3.0, delete_items никогда не прибегает к удалению всего:

• ids: [...] удаляет указанные элементы.

• query: {...} удаляет всё, что соответствует запросу.

• Передача обоих параметров отклоняется.

• Если не передано ни одного, ничего не удаляется и запрос не отправляется.

Чтобы удалить все элементы коллекции, запросите это явно:

{ "collection": "articles", "query": { "limit": -1 }, "confirm": true }

Примеры использования

"List all collections in my Directus instance"

"Create a new collection called 'blog_posts' with title, content, and published fields"

"Get all items from the 'products' collection where status is 'published'"

"Create a new flow that triggers on item creation in the 'orders' collection"

"Analyze the schema of the 'users' collection including relationships"

Устранение неполадок

MCP-сервер не подключается

1. Убедитесь, что Directus запущен: ваш экземпляр Directus должен быть доступен по настроенному URL

2. Проверьте права токена: API-токен должен иметь соответствующие права для операций, которые вы хотите выполнять

3. Перезапустите IDE: после изменения конфигурации MCP полностью перезапустите вашу IDE

4. Проверьте журналы: поищите ошибки, связанные с MCP, в консоли разработчика вашей IDE

Ошибки прав доступа

Убедитесь, что ваш Directus-токен имеет необходимые права:

• Токен администратора для полного доступа

• Или настройте права конкретной роли для коллекций, к которым вам нужен доступ

Тайм-аут подключения

Если вы используете удалённый экземпляр Directus:

• Проверьте, что URL корректен и доступен

• Проверьте настройки брандмауэра и сети

• Убедитесь, что CORS правильно настроен в Directus

Разработка

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run server
npm start

# Type check
npm run typecheck

# Lint
npm run lint

Тестирование

Проект включает наборы модульных, интеграционных и сквозных тестов (vitest). Пороги покрытия (95% операторов/строк/функций/веток) обязательны — при значениях ниже них тестовый прогон завершается неудачей.

# Unit + integration tests
npm test

# With coverage report (coverage/ — text, html, lcov, json-summary)
npm run test:coverage

# End-to-end: builds, then spawns the real server over stdio against a mock Directus
npm run test:e2e

# Everything
npm run test:all

# Refresh the README coverage badges from the last coverage run
npm run badges

Живая проверка на реальном Directus

tests/live/demo.mjs прогоняет все 34 инструмента на реальном экземпляре через stdio. Он намеренно вынесен за пределы npm test — ему нужны учётные данные и доступный сервер, поэтому это ручная проверка, а не CI-проверка.

# Read-only + guard phases (touches nothing)
ENV_FILE=.env.mdbaudio npm run test:live

# Also create, mutate and drop a scratch mcp_demo_<stamp> collection
ENV_FILE=.env.mdbaudio npm run test:live -- --write

# Additionally exercise apply_schema, confined to that scratch collection
ENV_FILE=.env.mdbaudio npm run test:live -- --write --apply-schema

Учётные данные читаются из ENV_FILE (по умолчанию .env.mdbaudio), поэтому они никогда не проходят через историю оболочки. Результаты сообщаются по каждому инструменту как pass / refused-by-instance / fail, что отделяет «этот сервер сломан» от «этот экземпляр отказал». --apply-schema применяет diff в режиме merge, который даёт строго аддитивный diff, поэтому он может лишь заново создать временную коллекцию — он не может удалить ничего, что уже существовало. Очистка выполняется, даже если более ранний этап завершился неудачей.

Сквозной набор тестов использует официальный клиент MCP SDK (StdioClientTransport) для запуска dist/index.js как подпроцесса, общающегося с внутрипроцессным моком Directus на эфемерном порту — не требуется ни реальный экземпляр Directus, ни доступ к сети.

Участие в разработке

Вклад приветствуется! Пожалуйста, не стесняйтесь отправлять Pull Request.

1. Сделайте форк репозитория

2. Создайте ветку для вашей функции (git checkout -b feature/amazing-feature)

3. Зафиксируйте изменения (git commit -m 'Add some amazing feature')

4. Отправьте ветку в репозиторий (git push origin feature/amazing-feature)

5. Откройте Pull Request

Лицензия

MIT © Jorge Domingues Nunes

Ссылки

• npm-пакет

• Репозиторий GitHub

• Документация Directus

• Спецификация протокола MCP