mcp-keycloak

Сервер Model Context Protocol для Keycloak. Он позволяет MCP-совместимому клиенту (Claude Desktop, Claude Code и т. д.) просматривать и управлять realm, пользователями, клиентами, ролями и группами Keycloak — при этом безопасность полностью контролируется флагами.

Цель дизайна — безопасность по умолчанию: сервер запускается в режиме read-only, работает только со списком разрешённых realm (allowlist), защищает чувствительные realm от изменения и допускает деструктивные операции только после явного opt-in.

Возможности

• Multi-realm — каждый инструмент принимает аргумент realm; его область действия можно ограничить с помощью allowlist.

• Режимы доступа — read-only → read-write → admin, выстроены по уровням: режим никогда не открывает инструменты выше своего уровня.

• Флаги безопасности — allowlist realm, защита чувствительных realm, контроль удаления, dry-run и журнал аудита в формате JSON (см. ниже).

• Две стратегии аутентификации — сервисный аккаунт конфиденциального клиента (рекомендуется) или имя пользователя и пароль администратора.

• Без тяжёлых зависимостей — тонкий Admin REST-клиент на основе fetch, плюс MCP SDK и zod.

Related MCP server: mcp-keycloak-admin

Модель безопасности

Эти слои независимы — например, режим admin с KEYCLOAK_ALLOW_DELETE=false может создавать и обновлять пользователей, но не может их удалять.

Инструменты

Чтение (read-only и выше): list_realms, get_realm, list_users, get_user, count_users, list_clients, list_realm_roles, list_groups

Запись (read-write и выше): create_user, update_user, reset_password, logout_user

Администрирование (admin): delete_user

Работа с вашим MCP-клиентом

Работает с Claude Code, Claude Desktop, Cursor, OpenAI Codex CLI, Windsurf, VS Code (Copilot) и любым другим MCP-клиентом — о настройке каждого клиента см. docs/CLIENTS.md.

Установка

npm install
npm run build

Настройка

Скопируйте .env.example и заполните его, либо задайте переменные напрямую в конфигурации вашего MCP-клиента. Рекомендуемые учётные данные — конфиденциальный клиент (confidential client) с нужными вам ролями realm-management.

Запуск с Claude Desktop / Claude Code

Добавьте в конфигурацию вашего MCP-клиента (claude_desktop_config.json или через claude mcp add):

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-keycloak/dist/index.js"],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_CLIENT_ID": "admin-cli",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "KEYCLOAK_MODE": "read-only",
        "KEYCLOAK_REALM_ALLOWLIST": "app,customers"
      }
    }
  }
}

Повышайте KEYCLOAK_MODE до read-write (а для удалений — admin + KEYCLOAK_ALLOW_DELETE=true) только тогда, когда вы намерены позволить модели вносить изменения.

Разработка

npm run dev        # watch mode
npm test           # unit tests for the security policy
npm run typecheck

Публикация

Сервер поставляется с server.json для официального реестра MCP и со значением mcpName в mcpName для проверки владения пакетом на npm. О публикации на npm и добавлении в список MCP-реестра, Smithery, Glama, Cursor и PulseMCP см. PUBLISHING.md.

Лицензия

MIT