Keycloak MCP Server

Сервер Model Context Protocol (MCP), предоставляющий интерфейс на естественном языке для управления идентификацией и доступом в Keycloak через его REST API. Этот сервер позволяет ИИ-агентам беспрепятственно выполнять задачи по управлению пользователями, настройке клиентов, администрированию областей (realms) и управлению доступом на основе ролей.

Обзор

Keycloak MCP Server устраняет разрыв между ИИ-приложениями и мощными возможностями управления идентификацией Keycloak. Независимо от того, создаете ли вы ИИ-помощника, которому нужно управлять пользователями, настраивать клиентов или обрабатывать сложные сценарии авторизации, этот сервер предоставляет необходимые инструменты с помощью простых команд на естественном языке.

Related MCP server: Advanced Keycloak MCP server

Возможности

🔐 Комплексное управление пользователями

Управляйте жизненным циклом пользователей от создания до удаления, включая сброс паролей, управление сессиями и обновление атрибутов пользователей.

🏢 Настройка клиентов

Создавайте и настраивайте OAuth2/OIDC-клиенты, управляйте секретами клиентов и программно обрабатывайте сервисные учетные записи.

👥 Управление доступом на основе ролей (RBAC)

Определяйте и назначайте роли для областей (realm) и конкретных клиентов, управляйте правами пользователей и внедряйте детальный контроль доступа.

🏛️ Администрирование областей (Realms)

Настраивайте параметры областей, управляйте группами по умолчанию, обрабатывайте конфигурации событий и контролируйте политики на уровне всей области.

🔐 Управление аутентификацией

Комплексное управление потоками аутентификации, включая создание, обновление и удаление потоков, управление выполнениями и настройку аутентификаторов.

🔄 Управление группами

Организуйте пользователей в группы, управляйте иерархиями групп и эффективно обрабатывайте разрешения на основе групп.

Установка

Установка через Smithery

Чтобы автоматически установить mcp-keycloak для Claude Desktop через Smithery:

npx -y @smithery/cli install mcp-keycloak --client claude

Быстрый старт

Установите с помощью pip:

pip install mcp-keycloak

Установка для разработки

Клонируйте репозиторий и установите зависимости:

git clone https://github.com/idoyudha/mcp-keycloak.git
cd mcp-keycloak
pip install -e .

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

Сервер можно настроить с помощью переменных окружения или файла .env:

# Required configuration
SERVER_URL=https://your-keycloak-server.com
USERNAME=admin-username
PASSWORD=admin-password
REALM_NAME=your-realm

# Optional OAuth2 client configuration
CLIENT_ID=optional-client-id
CLIENT_SECRET=optional-client-secret

Инструменты

Keycloak MCP Server предоставляет полный набор инструментов, организованных по функциональности:

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

Полное управление жизненным циклом пользователей, включая:

• list_users — список пользователей с пагинацией и фильтрацией

• create_user / update_user / delete_user — полные CRUD-операции

• reset_user_password — управление паролями

• get_user_sessions / logout_user — контроль сессий

• count_users — статистика пользователей

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

Настройка OAuth2/OIDC-клиентов:

• list_clients / get_client / create_client — операции с клиентами

• get_client_secret / regenerate_client_secret — управление секретами

• get_client_service_account — доступ к сервисным учетным записям

• update_client / delete_client — модификация клиентов

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

Детальный контроль разрешений:

• list_realm_roles / create_realm_role — операции с ролями области

• list_client_roles / create_client_role — роли, специфичные для клиента

• assign_realm_role_to_user / remove_realm_role_from_user — назначение ролей

• get_user_realm_roles / assign_client_role_to_user — запросы ролей пользователей

Управление группами

Иерархическая организация пользователей:

• list_groups / create_group / update_group — операции с группами

• get_group_members / add_user_to_group — управление членством

• get_user_groups / remove_user_from_group — ассоциации пользователей с группами

Администрирование областей (Realms)

Конфигурация всей системы:

• get_accessible_realms — список доступных областей

• get_realm_info / update_realm_settings — конфигурация области

• get_realm_events_config / update_realm_events_config — управление событиями

• add_realm_default_group / remove_realm_default_group — настройки по умолчанию

Управление аутентификацией

Полный контроль потоков аутентификации:

• list_authentication_flows / get_authentication_flow — управление потоками

• create_authentication_flow / update_authentication_flow — CRUD-операции с потоками

• delete_authentication_flow / copy_authentication_flow — модификация потоков

• get_flow_executions / update_flow_executions — управление выполнениями

• create_execution / delete_execution — жизненный цикл выполнения

• get_authenticator_config / create_authenticator_config — управление конфигурацией

• get_required_actions / update_required_action — контроль обязательных действий

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

Запуск сервера

Сервер поддерживает как stdio (по умолчанию), так и HTTP-транспорт. Файл конфигурации smithery.yaml позволяет развертывание на платформе Smithery и автоматическую установку через Smithery CLI:

# Run in stdio mode (default, for local CLI tools)
python -m src.main

# Run in HTTP mode with streamable HTTP transport
TRANSPORT=http python -m src.main

# Run HTTP mode on a custom port
TRANSPORT=http PORT=8080 python -m src.main

# Or use the convenience script:
./scripts/run_server.sh         # stdio mode (default)
./scripts/run_server.sh http    # HTTP mode
PORT=8080 ./scripts/run_server.sh http  # HTTP mode on custom port

При использовании HTTP-транспорта сервер будет доступен по адресу http://127.0.0.1:8000/mcp/ (или вашему пользовательскому PORT).

HTTP-транспорт

Keycloak MCP Server поддерживает режим HTTP-транспорта, который предлагает несколько преимуществ:

• Сетевая доступность: доступ к серверу с любой машины в вашей сети

• Несколько клиентов: поддержка одновременных подключений от нескольких ИИ-клиентов

• Гибкость интеграции: легкая интеграция с веб-приложениями и API

• Балансировка нагрузки: развертывание за обратным прокси-сервером для масштабируемости

Детали протокола HTTP

HTTP-транспорт следует спецификации MCP для Streamable HTTP. FastMCP автоматически обрабатывает все требования протокола:

• Endpoint: все коммуникации происходят через endpoint /mcp/

• Метод запроса: POST-запросы с сообщениями JSON-RPC 2.0

• Типы контента:

  • Сервер возвращает Content-Type: application/json для одиночных ответов

  • Сервер возвращает Content-Type: text/event-stream для потоковых ответов

• Заголовки Accept: клиенты должны включать Accept: application/json, text/event-stream

• Формат сообщения: все сообщения используют формат JSON-RPC 2.0, кодировка UTF-8

FastMCP автоматически определяет, возвращать ли одиночный JSON-ответ или SSE-поток, основываясь на типе запроса и необходимости потоковой передачи.

Подключение к HTTP-серверу

При работе в режиме HTTP клиенты могут подключаться к:

http://127.0.0.1:8000/mcp/

Пример запроса клиента:

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "list_tools", "id": 1}'

Реализация безопасности

HTTP-транспорт реализует все требования безопасности спецификации MCP:

✅ Проверка заголовка Origin (ОБЯЗАТЕЛЬНО)

• Автоматически проверяет заголовки Origin для предотвращения атак типа DNS rebinding

• Разрешает подключения только с источников localhost и 127.0.0.1

• Блокирует неавторизованные кросс-доменные запросы

✅ Привязка к Localhost (РЕКОМЕНДУЕТСЯ)

• Привязывается только к 127.0.0.1 для предотвращения сетевых атак

• Следует рекомендациям безопасности спецификации MCP

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

• Сервер работает без требований аутентификации для упрощения локальной разработки

• Подходит для использования на localhost и в доверенных средах

Для производственных развертываний учитывайте следующее:

• Используйте HTTPS с надлежащими сертификатами

• Развертывайте за обратным прокси-сервером (nginx, Apache)

• Установите соответствующие правила брандмауэра

• При необходимости внедрите аутентификацию на уровне обратного прокси-сервера

Примеры интеграции

Предварительные требования

Перед интеграцией Keycloak MCP Server убедитесь, что у вас установлено одно из следующего:

• uvx (рекомендуется): установите через pip install uvx или pipx install uvx

• uv: следуйте инструкциям по установке

• npm/npx: для установки Smithery (поставляется с Node.js)

Вариант 1: Использование Smithery CLI (рекомендуется)

Самый простой способ — автоматически настраивает все для Claude Desktop:

npx @smithery/cli install @idoyudha/mcp-keycloak --client claude

Эта команда запросит необходимые значения конфигурации и автоматически настроит сервер.

Вариант 2: Использование uvx (ручная настройка)

Клонирование не требуется! Добавьте в ваш claude_desktop_config.json:

{
  "mcpServers": {
    "keycloak": {
      "command": "uvx",
      "args": ["mcp-keycloak"],
      "env": {
        "SERVER_URL": "https://your-keycloak.com",
        "USERNAME": "admin",
        "PASSWORD": "admin-password",
        "REALM_NAME": "your-realm"
      }
    }
  }
}

Вариант 3: Настройка локальной разработки

Для разработки или кастомизации:

1. Клонируйте репозиторий:

git clone https://github.com/idoyudha/mcp-keycloak.git
cd mcp-keycloak

2. Добавьте в ваш claude_desktop_config.json:

{
  "mcpServers": {
    "keycloak": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-keycloak",
        "run",
        "python",
        "-m",
        "src"
      ],
      "env": {
        "SERVER_URL": "https://your-keycloak.com",
        "USERNAME": "admin",
        "PASSWORD": "admin-password",
        "REALM_NAME": "your-realm"
      }
    }
  }
}

💡 Краткие советы:

• Замените /path/to/mcp-keycloak на фактический путь, куда вы клонировали репозиторий

• Убедитесь, что URL вашего сервера Keycloak включает протокол (https:// или http://)

• REALM_NAME должен соответствовать существующей области в вашем экземпляре Keycloak

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

🤖 Управление идентификацией с помощью ИИ

Создавайте ИИ-помощников, которые могут обрабатывать онбординг пользователей, управление разрешениями и контроль доступа с помощью команд на естественном языке.

🔄 Автоматизированная подготовка пользователей

Создавайте рабочие процессы, которые автоматически подготавливают пользователей, назначают роли и настраивают клиентские приложения на основе бизнес-правил.

📊 Аналитика идентификации

Запрашивайте и анализируйте данные пользователей, информацию о сессиях и шаблоны доступа, чтобы получить представление о вашей инфраструктуре идентификации.

🚀 Интеграция с DevOps

Интегрируйте управление Keycloak в ваши CI/CD-конвейеры, позволяя автоматизировать настройку сервисов идентификации.

Требования

• Python 3.8 или выше

• Сервер Keycloak (протестировано с Keycloak 18+)

• Административный доступ к области Keycloak

Лицензия

Этот проект лицензирован по лицензии MIT — подробности см. в файле LICENSE.

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

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

Поддержка

По вопросам, проблемам или предложениям, пожалуйста, посетите GitHub-репозиторий.