skycloak-mcp

Официальный сервер Model Context Protocol для Skycloak (управляемый Keycloak): управляйте своими кластерами, областями, приложениями и SSO из любого MCP-клиента (Claude Desktop, Claude Code, Cursor).

Статус: ранний релиз. Набор инструментов расширяется; смотрите список изменений для информации о доступных функциях.

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

claude mcp add --transport http skycloak https://mcp.skycloak.io

Никакого API-ключа, никакого идентификатора клиента, никакой настройки. Ваш браузер открывается, вы входите в Skycloak, и инструменты появляются. Любой MCP-клиент, поддерживающий потоковый HTTP, работает так же: передайте ему URL и ничего больше.

Затем попросите что-нибудь:

• "Какие из моих кластеров Keycloak отстают по обновлениям?"

• "Создай промежуточную область на EU-кластере со входом через Google и GitHub."

• "Кто был добавлен в рабочую область за последнюю неделю?"

• "Настрой SIEM-назначение для пересылки событий администратора на наш вебхук Datadog."

Related MCP server: MCP Authentik

Аутентификация и безопасность

• Размещённый HTTP с OAuth (без настройки учётных данных). Направьте клиент на https://mcp.skycloak.io без заголовка. Сервер отвечает 401 с указателем на свои метаданные RFC 9728 в /.well-known/oauth-protected-resource, клиент выполняет браузерный код авторизации на основе потока входа в Skycloak, а полученный токен доступа обменивается на краткосрочный API-ключ с областью действия рабочей области, на котором работает сессия. Ключ действует час и автоматически обновляется. Ничего не сохраняется в конфигурации клиента.

• Размещённый HTTP с API-ключом. Создайте ключ в панели управления Skycloak и отправляйте его как Authorization: Bearer <key> (или API-Key: <key>). Каждый запрос несёт собственные учётные данные и работает только от имени рабочей области этих учётных данных. Сервер не хранит состояние сессии, поэтому запрос никогда не наследует данные другого вызывающего. Ключи не проверяются перед использованием: авторитетом является API Skycloak, поэтому недействительный ключ вернёт 401 при первом вызове инструмента, а не при подключении.

• Инструменты соответствуют вашей роли. При OAuth список инструментов сокращается до разрешённых областью сессии, поэтому участник рабочей области с правами только на чтение не увидит инструментов записи, которые вернули бы 403. С API-ключом регистрируется вся поверхность, так как области ключа не видны серверу, и несанкционированный вызов возвращает 403 от API.

• Локальный stdio. Запустите skycloak-mcp init и подтвердите в браузере (протокол авторизации устройства OAuth 2.0). Он создаёт API-ключ с областью рабочей области, сохраняет его в системной связке ключей и автоматически определяет вашу рабочую область по умолчанию (передайте --workspace <id>, чтобы выбрать другую). skycloak-mcp logout удаляет сохранённый ключ.

• Безголовый / CI. Установите переменную окружения SKYCLOAK_API_KEY (создайте ключ в панели управления Skycloak), чтобы полностью пропустить браузер. Она всегда имеет приоритет над связкой ключей.

• Запись ограничивается вашими учётными данными, а не флагом. Размещённый сервер на https://mcp.skycloak.io работает с поддержкой записи, и то, что вы можете изменить, ограничено областями вашего ключа и вашей ролью в рабочей области: участник только для чтения не может ничего изменить, независимо от списка инструментов. Добавьте ?readonly=true к URL, чтобы принудительно установить поверхность инструментов только для чтения для сессии. Локальный двоичный файл работает наоборот и не регистрирует инструменты записи, если не запущен с --allow-writes.

• Учётные данные кластера — опциональны. get_cluster_credentials возвращает учётные данные администратора кластера Keycloak, которые помощник, удерживающий ключ, затем увидит, поэтому init не запрашивает эту область по умолчанию. Используйте ключ, который её содержит: создайте его в панели управления или через stdio войдите с skycloak-mcp init --allow-credentials. Без этого инструмент возвращает 403, объясняющий оба пути.

• Деструктивные инструменты требуют подтверждения: удаление области, например, требует явного аргумента confirm=true.

• Запросы ограничиваются по скорости в соответствии с вашим планом Skycloak; при ответе 429 сервер показывает Retry-After.

Инструменты

129 инструментов: 58 только для чтения и 71 для записи. Инструменты только для чтения всегда доступны. На размещённом сервере инструменты записи также зарегистрированы и ограничены областями ваших учётных данных; локальный двоичный файл регистрирует их только при запуске с --allow-writes.

Имена инструментов содержат префикс skycloak_, который опущен в таблице ниже, поэтому list_clusters в вашем клиенте будет skycloak_list_clusters.

Соглашения: деструктивные инструменты (delete_*, uninstall_extension, cancel_cluster_upgrade) требуют confirm=true. create_cluster асинхронен: опрашивайте get_cluster, пока кластер не станет available. create_domain возвращает DNS-записи, которые клиент должен создать; verify_domain запускает проверку DNS. set_theme_assignment активирует пользовательскую тему в соответствии с типом темы Keycloak (пустая строка сбрасывает на встроенную по умолчанию). update_cluster_security не затрагивает настройки CAPTCHA. Импорт/экспорт realm перемещает конфигурацию одного realm и отличается от create_export, который выгружает базу данных всего кластера: оба асинхронны, а архив realm всегда зашифрован, поэтому пароль, использованный для экспорта, необходим для повторного импорта. Realm можно импортировать напрямую из существующего экспорта (source_export_id) или из загруженного архива (create_realm_import_upload_url, PUT, затем upload_s3_key); импорт создаёт realm и отклоняет совпадение имён, а не перезаписывает, и требует confirm=true, так как переносит пользователей и учётные данные.

Подключение

Для размещённого HTTP самый простой путь — OAuth, который вообще не требует учётных данных:

claude mcp add --transport http skycloak https://mcp.skycloak.io

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

claude mcp add --transport http skycloak "https://mcp.skycloak.io?workspace=<workspace-id>"

В противном случае создайте API-ключ в панели управления Skycloak и настройте ваш MCP-клиент на отправку его как bearer-токена:

claude mcp add --transport http skycloak https://mcp.skycloak.io --header "Authorization: Bearer sk_sc_XXX"

Это добавляет следующее в .claude.json:

{
  "mcpServers": {
    "skycloak": {
      "type": "http",
      "url": "https://mcp.skycloak.io",
      "headers": {
        "Authorization": "Bearer sk_sc_XXX"
      }
    }
  }
}

Для локального stdio войдите один раз, затем укажите вашему клиенту на skycloak-mcp run:

skycloak-mcp init        # one-time browser sign-in; stores a key in your keychain

Claude Desktop / Cursor (локальный, stdio):

{
  "mcpServers": {
    "skycloak": {
      "command": "skycloak-mcp",
      "args": ["run", "--transport", "stdio"]
    }
  }
}

Claude Code:

claude mcp add skycloak -- skycloak-mcp run --transport stdio

Для headless / CI (без браузера) пропустите init и передайте ключ: добавьте "env": { "SKYCLOAK_API_KEY": "sk_sc_..." } в конфиг, или claude mcp add skycloak --env SKYCLOAK_API_KEY=sk_sc_... -- skycloak-mcp run --transport stdio.

Добавляйте --allow-writes только если планируете вносить изменения (войдите с skycloak-mcp init --allow-writes или используйте ключ с правами на запись).

Добавьте ?readonly=true к URL размещённого HTTP, чтобы открыть только инструменты чтения для этой HTTP-сессии, или ?readonly=false, чтобы запросить поверхность инструментов с возможностью записи. Параметр запроса по умолчанию равен false, но инструменты записи регистрируются только если сервер был запущен с --allow-writes.

Добавьте ?workspace=<uuid>, чтобы выбрать, в каком рабочем пространстве будет действовать OAuth-сессия. Это нужно только если вы принадлежите к нескольким рабочим пространствам; если пространство одно, сервер выбирает его сам, а если вы принадлежите к нескольким и не указали ни одного, соединение не удастся, и вы получите сообщение с их списком.

Запуск HTTP-транспорта

skycloak-mcp run --transport http --http-addr :8080

Ему не нужны собственные учётные данные: вызывающие предоставляют их в каждом запросе, поэтому при развёртывании ничего не внедряется. GET /healthz и GET /readyz не требуют аутентификации и сообщают только о том, что процесс запущен; они намеренно не обращаются к API Skycloak, поэтому временная проблема вышестоящего сервиса не может одновременно привести к сбою проверки всех реплик. Сервер не хранит состояние сессии, поэтому репликам не нужна привязка сессий, и их можно свободно масштабировать или обновлять. SIGTERM останавливает новые соединения и завершает выполняющиеся вызовы.

OAuth-путь включается всегда, когда заданы SKYCLOAK_ISSUER и SKYCLOAK_DASHBOARD_URL, а по умолчанию они заданы. GET /.well-known/oauth-protected-resource тогда обслуживается без аутентификации и указывает realm как сервер авторизации. Его значение resource берётся из SKYCLOAK_PUBLIC_URL, если он задан, иначе — из собственных Host и схемы запроса, так что для развёртывания с одним хостом за входящим прокси не требуется дополнительной настройки. Схема берётся из X-Forwarded-Proto, если он присутствует, иначе по умолчанию используется https для всех, кроме loopback-хоста, поскольку TLS завершается вышестоящим сервером, и публикация идентификатора http:// не соответствовала бы URL, к которому подключился клиент. Установите SKYCLOAK_PUBLIC_URL, если ваш входящий прокси перезаписывает Host. В документе также перечислены openid profile email как scopes_supported, а в вызове WWW-Authenticate они повторяются как параметр scope, поэтому клиент, читающий любой из них, запрашивает их у realm: openid обязателен, потому что при обмене токена панель вызывает конечную точку userinfo Keycloak, а Keycloak отказывает в токене, выданном без него. Токен, полученный без него, отклоняется при проверке с кодом 401 и вызовом, а не передаётся на обмен, который не может быть успешным, поэтому клиент, всё ещё имеющий грант до этого, прекращает повторные попытки и входит снова. Если обнулить любую из переменных issuer или dashboard, OAuth полностью отключается, и сервер снова начинает требовать только API-ключ.

При запуске выводится одна строка с разрешёнными настройками (oauth=, issuer=, dashboard=, public_url=, endpoint=, allow_writes=), поэтому неправильно настроенное развёртывание можно обнаружить без повторного развёртывания. Каждый запрос, отклонённый на OAuth-пути, записывает одну строку с указанием этапа, на котором произошла ошибка (verify, exchange или scopes), статуса, полученного вызывающим, и базовой ошибки. При сбое проверки добавляется проверка, отклонившая токен (expired, wrong_issuer, bad_signature, unknown_key_id, wrong_token_type, no_openid_scope и т.д.); при сбое обмена добавляется статус панели и вызванный хост. Вызывающий отображается как субъект токена после его проверки и никогда не отображается как учётные данные: токен доступа, заголовок Authorization и выпущенный API-ключ никогда не записываются в журнал.

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

Команды: init (вход через браузер), run (запуск), logout (удаление сохранённого ключа). init принимает --workspace <id>, --allow-writes, --allow-credentials и --ttl-days (по умолчанию 90).

Разработка

make build      # build the server binary
make test       # unit tests
make run        # run on stdio for local testing
make inspector  # MCP Inspector against the local binary
make lint       # golangci-lint
make generate   # regenerate the API client from the OpenAPI spec

Клиент API в internal/apiclient генерируется из спецификации OpenAPI Skycloak с помощью oapi-codegen.

Синхронизация с API

Клиент в internal/apiclient генерируется из internal/apiclient/openapi.yaml с помощью oapi-codegen; выполните make generate, чтобы обновить его. CI завершается ошибкой, если зафиксированный сгенерированный код отклоняется от спецификации. Запросы повторяются при получении 429/5xx с экспоненциальной задержкой с учётом Retry-After.

Распространение

Выпускается как бинарные файлы GitHub и образ контейнера ghcr.io/sky-cloak/skycloak-mcp для каждого тега, а также публикуется в MCP Registry как io.skycloak/skycloak-mcp. Большинству людей не нужно ни то, ни другое: размещённый сервер не требует установки.

Безопасность

Пожалуйста, сообщайте об уязвимостях конфиденциально. См. SECURITY.md.

Участники

Создано в Skycloak Гиллиано Моларом, Невиллом Оманджи и Афиласом. История репозитория была сжата при его открытии, поэтому журнал коммитов не отражает, кто что написал.

Лицензия

Apache-2.0. Описание OpenAPI в internal/apiclient/openapi.yaml генерируется из API платформы Skycloak и является собственностью (c) Skycloak; оно включено сюда, чтобы клиент можно было генерировать и проверять. См. NOTICE.