mcp-keycloak

mcp-keycloak

Um servidor Model Context Protocol para Keycloak. Ele permite que um cliente compatível com MCP (Claude Desktop, Claude Code, etc.) inspecione e gerencie realms, usuários, clientes, papéis e grupos do Keycloak — com a segurança controlada inteiramente por flags.

O objetivo do design é seguro por padrão: ele inicia somente leitura, limita-se a uma lista de permissões de realms, protege realms sensíveis de mutações e condiciona operações destrutivas a uma aceitação explícita.

Recursos

• Multi-realm — cada ferramenta aceita um argumento realm; escopo com uma lista de permissões.
• Modos de acesso — read-only → read-write → admin, em camadas, de modo que um modo nunca exponha ferramentas acima do seu nível.
• Flags de segurança — lista de permissões de realms, realms protegidos, bloqueio de exclusão, simulação (dry-run) e registro de auditoria em JSON (veja abaixo).
• Duas estratégias de autenticação — conta de serviço de cliente confidencial (recomendada) ou nome de usuário/senha de administrador.
• Zero dependências pesadas — um cliente Admin REST fino baseado em fetch, além do SDK MCP e zod.

Modelo de segurança

Preocupação	Flag	Padrão	Efeito
O que o servidor pode fazer?	KEYCLOAK_MODE	read-only	read-only expõe apenas ferramentas de leitura; read-write adiciona mutações; admin adiciona ferramentas destrutivas. Ferramentas acima do modo nunca são registradas.
Quais realms estão no escopo?	KEYCLOAK_REALM_ALLOWLIST	(todos)	Separados por vírgula. Quando definido, qualquer operação em um realm fora da lista é recusada.
Quais realms são somente leitura para sempre?	KEYCLOAK_PROTECTED_REALMS	master	Realms protegidos podem ser lidos, mas nunca mutados ou excluídos, independentemente do modo.
Pode excluir?	KEYCLOAK_ALLOW_DELETE	false	Ferramentas delete_* exigem isso e o modo admin.
Pré-visualizar sem tocar no Keycloak	KEYCLOAK_DRY_RUN	false	Ferramentas de escrita/admin validam + registram a intenção e retornam sem chamar o Keycloak.
Trilha de auditoria	KEYCLOAK_AUDIT_LOG	true	Emite uma linha JSON para stderr por operação protegida (ALLOW / DENY / DRY_RUN).

Essas camadas são independentes — por exemplo, o modo admin com KEYCLOAK_ALLOW_DELETE=false pode criar e atualizar usuários, mas não pode excluí-los.

Ferramentas

Leitura (read-only+): list_realms, get_realm, list_users, get_user, count_users, list_clients, list_realm_roles, list_groups

Escrita (read-write+): create_user, update_user, reset_password, logout_user

Admin (admin): delete_user

Início rápido — adicione ao seu agente

Publicado no npm como @dockndevai/mcp-keycloak. Sem necessidade de clone ou build — seu cliente MCP o executa sob demanda com npx. Comece no modo read-only; veja .env.example para todas as variáveis e docs/CLIENTS.md para o guia completo por cliente.

Claude Code (CLI)

claude mcp add keycloak -e KEYCLOAK_URL="https://keycloak.example.com" -e KEYCLOAK_CLIENT_ID="admin-cli" -e KEYCLOAK_CLIENT_SECRET="your-secret" -e KEYCLOAK_MODE="read-only" -- npx -y @dockndevai/mcp-keycloak

Claude Desktop · Cursor · Windsurf — mesmo bloco em claude_desktop_config.json, .cursor/mcp.json ou ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-keycloak"
      ],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_CLIENT_ID": "admin-cli",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "KEYCLOAK_MODE": "read-only"
      }
    }
  }
}

OpenAI Codex CLI — em ~/.codex/config.toml:

[mcp_servers.keycloak]
command = "npx"
args = ["-y", "@dockndevai/mcp-keycloak"]
env = { KEYCLOAK_URL = "https://keycloak.example.com", KEYCLOAK_CLIENT_ID = "admin-cli", KEYCLOAK_CLIENT_SECRET = "your-secret", KEYCLOAK_MODE = "read-only" }

VS Code (GitHub Copilot, modo Agente) — em .vscode/mcp.json:

{
  "servers": {
    "keycloak": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-keycloak"
      ],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_CLIENT_ID": "admin-cli",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "KEYCLOAK_MODE": "read-only"
      }
    }
  }
}

Configurar

Copie .env.example e preencha, ou defina as variáveis diretamente na configuração do seu cliente MCP. Um cliente confidencial com os papéis realm-management que você precisa é a credencial recomendada.

Executar a partir do código-fonte (desenvolvimento)

Prefira o pacote publicado acima. Para executar a partir de um clone:

npm install
npm run build
node dist/index.js   # with the environment variables set

Desenvolver

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

Publicação

Este servidor inclui um server.json para o registro oficial do MCP e um mcpName para validação de propriedade no npm. Veja PUBLISHING.md para publicar no npm e listar no registro MCP, Smithery, Glama, Cursor e PulseMCP.

Licença

MIT