Keycloak MCP Server

Servidor de Protocolo de Contexto Model (MCP) para Keycloak

Um servidor abrangente de Protocolo de Contexto Model (MCP) para administração do Keycloak, fornecendo mais de 80 ferramentas para gerenciar usuários, realms, clientes, papéis, grupos, sessões, eventos, organizações, mapeadores de protocolo, atributos de usuário, escopos de cliente e provedores de identidade diretamente de assistentes de IA como Claude Desktop ou Cursor AI.

🚀 Recursos

👤 Gerenciamento de Usuários

• ✅ Criar, atualizar e excluir usuários
• ✅ Listar, pesquisar e obter detalhes de usuários
• ✅ Redefinir senhas de usuários
• ✅ Encerrar sessões de usuários
• ✅ Gerenciar papéis e grupos de usuários
• ✅ NOVO: Gerenciamento de atributos de usuário (crítico para dados organizacionais)

🏛️ Gerenciamento de Realms

• ✅ Listar, criar, atualizar e excluir realms
• ✅ Obter configurações e definições detalhadas de realms
• ✅ Gerenciar políticas de segurança em nível de realm

🔧 Gerenciamento de Clientes

• ✅ Registrar, atualizar e excluir clientes/aplicações
• ✅ Listar todos os clientes em realms
• ✅ Configurar definições de clientes e URIs de redirecionamento
• ✅ NOVO: Gerenciamento de mapeadores de protocolo (crítico para claims JWT)

🎭 Gerenciamento de Papéis

• ✅ Criar, atualizar e excluir papéis (nível de realm e cliente)
• ✅ Atribuir e remover papéis de usuários e grupos
• ✅ Listar todos os papéis e atribuições de papéis de usuários
• ✅ NOVO: Papéis compostos e hierarquias de papéis
• ✅ NOVO: Operações avançadas de papéis por ID
• ✅ NOVO: Encontrar usuários com papéis específicos

👥 Gerenciamento de Grupos

• ✅ Criar, atualizar e excluir grupos de usuários
• ✅ Adicionar e remover usuários de grupos
• ✅ Gerenciar estruturas hierárquicas de grupos
• ✅ NOVO: Gerenciamento de atributos de grupo
• ✅ NOVO: Gerenciamento de grupos filhos e subgrupos
• ✅ NOVO: Listagem e gerenciamento de membros de grupos

🏢 Gerenciamento de Organizações ⭐ NOVO

• ✅ Criar, atualizar e excluir organizações
• ✅ Adicionar e remover membros de organizações
• ✅ Listar organizações e membros
• ✅ Gerenciamento de atributos de organizações

🔗 Gerenciamento de Provedores de Identidade ⭐ NOVO

• ✅ Criar, atualizar e excluir provedores de identidade (SSO)
• ✅ Gerenciamento de mapeadores de provedores de identidade
• ✅ Configuração de provedores SAML e OIDC
• ✅ Mapeamento de atributos de usuários externos

🎯 Gerenciamento de Escopos de Cliente ⭐ NOVO

• ✅ Criar, atualizar e excluir escopos de cliente
• ✅ Mapeadores de protocolo para escopos de cliente
• ✅ Gerenciamento de escopos de token

📊 Gerenciamento de Sessões e Eventos

• ✅ Listar sessões de usuários ativas
• ✅ Monitorar eventos de autenticação e administração
• ✅ Limpar logs de eventos e gerenciar ciclos de vida de sessões

🛡️ Recursos Avançados

• ✅ Autenticação à prova de falhas com instâncias de cliente novas
• ✅ Tratamento abrangente de erros com registro detalhado
• ✅ Suporte multiplataforma (Windows, macOS, Linux)
• ✅ Pronto para produção com TypeScript e arquitetura robusta
• ✅ Claims JWT de Organização - Resolver visibilidade de organização em tokens
• ✅ Mais de 80 Ferramentas - Cobertura completa de administração do Keycloak

📋 Pré-requisitos

• Node.js 18 ou superior
• Instância do Keycloak em execução (local ou remota)
• Credenciais de administrador do Keycloak com permissões apropriadas
• Assistente de IA que suporte MCP (Claude Desktop, Cursor AI, etc.)

📦 Instalação

Instalação Global (Recomendada)

npm install -g keycloak-mcp-server

Usando NPX (Sem Necessidade de Instalação)

npx keycloak-mcp-server

Instalação em Projeto Local

npm install keycloak-mcp-server

Desenvolvimento Local

git clone https://github.com/M0-AR/keycloak-mcp-server.git
cd keycloak-mcp-server
npm install
npm run build

⚙️ Configuração

Para Cursor AI

Adicione ao seu arquivo de configuração MCP do Cursor (~/.cursor/mcp.json):

Opção 1: Usando NPX (Recomendado)

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": ["keycloak-mcp-server"],
      "env": {
        "KEYCLOAK_URL": "https://your-keycloak-instance.com",
        "KEYCLOAK_ADMIN": "your-admin-username",
        "KEYCLOAK_ADMIN_PASSWORD": "your-admin-password"
      }
    }
  }
}

Opção 2: Se Instalado Globalmente

{
  "mcpServers": {
    "keycloak": {
      "command": "keycloak-mcp-server",
      "env": {
        "KEYCLOAK_URL": "https://your-keycloak-instance.com", 
        "KEYCLOAK_ADMIN": "your-admin-username",
        "KEYCLOAK_ADMIN_PASSWORD": "your-admin-password"
      }
    }
  }
}

Para Claude Desktop

Adicione à sua configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": ["keycloak-mcp-server"],
      "env": {
        "KEYCLOAK_URL": "https://your-keycloak-instance.com",
        "KEYCLOAK_ADMIN": "your-admin-username",
        "KEYCLOAK_ADMIN_PASSWORD": "your-admin-password"
      }
    }
  }
}

🌍 Variáveis de Ambiente

Variável	Descrição	Padrão	Obrigatória
KEYCLOAK_URL	A URL base da sua instância do Keycloak	http://localhost:8080	✅
KEYCLOAK_ADMIN	Nome de usuário do administrador	admin	✅
KEYCLOAK_ADMIN_PASSWORD	Senha do administrador	admin	✅

🛠️ Ferramentas Disponíveis (Mais de 80 Ferramentas)

👤 Ferramentas de Gerenciamento de Usuários

create-user

Cria um novo usuário em um realm especificado.

Create a user in "master" realm: username "john.doe", email "john@example.com", first name "John", last name "Doe"

update-user

Atualiza informações do usuário (e-mail, nomes, status de ativação).

Update user "user-id-123" in "master" realm to change email to "newemail@example.com"

delete-user

Exclui um usuário de um realm.

Delete user with ID "user-id-123" from "master" realm

list-users

Lista todos os usuários em um realm.

List all users in the "master" realm

search-users

Pesquisa usuários com filtros (nome de usuário, e-mail, primeiro nome, sobrenome).

Search for users with email containing "wateen.io" in "master" realm, limit 10 results

get-user

Obtém informações detalhadas sobre um usuário específico.

Get details for user ID "user-id-123" in "master" realm

reset-user-password

Redefine a senha de um usuário.

Reset password for user "user-id-123" in "master" realm to "newPassword123", make it temporary

logout-user

Encerra todas as sessões de um usuário específico.

Logout all sessions for user "user-id-123" in "master" realm

set-user-attributes ⭐ NOVO

Define atributos de usuário (crítico para armazenamento de dados organizacionais).

Set organization attribute for user "user-id-123" in "master" realm: {"organization": ["wateen-corp"]}

get-user-attributes ⭐ NOVO

Obtém atributos de usuário, incluindo atributos não gerenciados.

Get all attributes for user "user-id-123" in "master" realm

🏛️ Ferramentas de Gerenciamento de Realms

list-realms

Lista todos os realms disponíveis.

Show me all available realms in Keycloak

create-realm

Cria um novo realm com configurações personalizáveis.

Create a new realm called "company" with display name "Company Realm", enabled

update-realm

Atualiza configurações e definições de realms.

Update realm "company" to change display name to "Updated Company"

delete-realm

Exclui um realm existente.

Delete the realm "test-realm"

get-realm-settings

Recupera configurações detalhadas de um realm.

Get detailed settings for the "master" realm

🔧 Ferramentas de Gerenciamento de Clientes

create-client

Registra um novo cliente/aplicação em um realm.

Create client "my-app" in "master" realm with redirect URIs ["http://localhost:3000/*"]

update-client

Atualiza configurações do cliente (URIs de redirecionamento, mapeadores de protocolo, etc.).

Update client "my-app" in "master" realm to add new redirect URI "https://app.example.com/*"

delete-client

Remove um cliente de um realm.

Delete client "old-app" from "master" realm

list-clients

Lista todos os clientes em um realm.

List all clients in the "master" realm

create-protocol-mapper ⭐ NOVO

Cria mapeadores de protocolo para clientes (crítico para claims JWT de organização).

Create organization group mapper for client "my-app" in "master" realm to include "organization" claim in JWT

update-protocol-mapper ⭐ NOVO

Atualiza mapeadores de protocolo existentes.

Update protocol mapper "mapper-id-123" for client "my-app" in "master" realm

delete-protocol-mapper ⭐ NOVO

Exclui mapeadores de protocolo de clientes.

Delete protocol mapper "mapper-id-123" from client "my-app" in "master" realm

list-protocol-mappers ⭐ NOVO

Lista todos os mapeadores de protocolo de um cliente.

List all protocol mappers for client "my-app" in "master" realm

🎯 Ferramentas de Gerenciamento de Escopos de Cliente ⭐ NOVO

create-client-scope

Cria um novo escopo de cliente para gerenciar escopos de token.

Create client scope "organization-scope" in "master" realm for organization claims

update-client-scope

Atualiza um escopo de cliente existente.

Update client scope "scope-id-123" in "master" realm to change description

delete-client-scope

Exclui um escopo de cliente.

Delete client scope "scope-id-123" from "master" realm

list-client-scopes

Lista todos os escopos de cliente em um realm.

List all client scopes in the "master" realm

get-client-scope

Obtém detalhes de um escopo de cliente específico.

Get details for client scope "scope-id-123" in "master" realm

create-client-scope-protocol-mapper ⭐ NOVO

Cria mapeadores de protocolo para escopos de cliente.

Create organization mapper for client scope "organization-scope" in "master" realm

update-client-scope-protocol-mapper ⭐ NOVO

Atualiza mapeadores de protocolo em escopos de cliente.

Update protocol mapper "mapper-id-123" in client scope "scope-id-456" in "master" realm

delete-client-scope-protocol-mapper ⭐ NOVO

Exclui mapeadores de protocolo de escopos de cliente.

Delete protocol mapper "mapper-id-123" from client scope "scope-id-456" in "master" realm

list-client-scope-protocol-mappers ⭐ NOVO

Lista mapeadores de protocolo para um escopo de cliente.

List all protocol mappers for client scope "scope-id-123" in "master" realm

🏢 Ferramentas de Gerenciamento de Organizações ⭐ NOVO

create-organization

Cria uma nova organização.

Create organization "wateen-corp" with description "Wateen Corporation" in "master" realm

update-organization

Atualiza uma organização existente.

Update organization "org-id-123" in "master" realm to change name to "Updated Corp"

delete-organization

Exclui uma organização.

Delete organization "org-id-123" from "master" realm

list-organizations

Lista todas as organizações em um realm.

List all organizations in "master" realm with search "wateen", limit 10

get-organization

Obtém detalhes de uma organização específica.

Get details for organization "org-id-123" in "master" realm

add-organization-member

Adiciona um usuário a uma organização.

Add user "user-id-123" to organization "org-id-456" in "master" realm

remove-organization-member

Remove um usuário de uma organização.

Remove user "user-id-123" from organization "org-id-456" in "master" realm

list-organization-members

Lista todos os membros de uma organização.

List all members of organization "org-id-123" in "master" realm, limit 20

🎭 Ferramentas de Gerenciamento de Papéis

create-role

Cria papéis em nível de realm ou cliente.

Create a realm role "manager" with description "Manager role" in "master" realm

update-role

Modifica atributos de papéis.

Update role "manager" in "master" realm to change description to "Updated manager role"

delete-role

Exclui papéis.

Delete role "old-role" from "master" realm

list-roles

Lista todos os papéis em um realm.

List all roles in the "master" realm

assign-role-to-user

Atribui um papel a um usuário.

Assign role "manager" to user "user-id-123" in "master" realm

remove-role-from-user

Remove um papel de um usuário.

Remove role "manager" from user "user-id-123" in "master" realm

get-user-roles

Obtém todos os papéis atribuídos a um usuário.

Get all roles for user "user-id-123" in "master" realm

create-composite-role ⭐ NOVO

Cria papéis compostos (hierarquias de papéis).

Create composite role from "parent-role-id" with child roles ["child-role-1", "child-role-2"] in "master" realm

get-composite-roles ⭐ NOVO

Obtém papéis compostos para um papel.

Get composite roles for role "role-id-123" in "master" realm, limit 10

delete-composite-roles ⭐ NOVO

Exclui papéis compostos de um papel.

Remove composite roles ["child-role-1", "child-role-2"] from role "parent-role-id" in "master" realm

get-role-by-id ⭐ NOVO

Obtém detalhes de papel por ID.

Get role details for role ID "role-id-123" in "master" realm

update-role-by-id ⭐ NOVO

Atualiza papel por ID.

Update role "role-id-123" in "master" realm to change name to "new-role-name"

delete-role-by-id ⭐ NOVO

Exclui papel por ID.

Delete role with ID "role-id-123" from "master" realm

find-users-with-role ⭐ NOVO

Encontra usuários com um papel específico.

Find all users with role "manager" in "master" realm, limit 20

assign-role-to-group ⭐ NOVO

Atribui um papel a um grupo.

Assign role "developer" to group "group-id-123" in "master" realm

remove-role-from-group ⭐ NOVO

Remove um papel de um grupo.

Remove role "developer" from group "group-id-123" in "master" realm

get-group-roles ⭐ NOVO

Obtém papéis atribuídos a um grupo.

Get all roles for group "group-id-123" in "master" realm

list-available-group-roles ⭐ NOVO

Lista papéis disponíveis para um grupo.

List available roles for group "group-id-123" in "master" realm

list-composite-group-roles ⭐ NOVO

Lista papéis compostos para um grupo.

List composite roles for group "group-id-123" in "master" realm

👥 Ferramentas de Gerenciamento de Grupos

create-group

Cria grupos de usuários.

Create a group called "developers" in "master" realm

update-group

Atualiza atributos de grupos.

Update group "group-id-123" in "master" realm to change name to "senior-developers"

delete-group

Exclui grupos.

Delete group "group-id-123" from "master" realm

list-groups

Lista todos os grupos em um realm.

List all groups in the "master" realm

manage-user-groups

Adiciona ou remove usuários de grupos.

Add user "user-id-123" to group "group-id-456" in "master" realm

set-group-attributes ⭐ NOVO

Define atributos de grupo (metadados de organização).

Set organization attributes for group "group-id-123" in "master" realm: {"department": ["engineering"]}

get-group-attributes ⭐ NOVO

Obtém atributos de grupo.

Get all attributes for group "group-id-123" in "master" realm

create-child-group ⭐ NOVO

Cria um grupo filho (subgrupo).

Create child group "junior-devs" under parent group "group-id-123" in "master" realm

list-sub-groups ⭐ NOVO

Lista subgrupos de um grupo pai.

List subgroups of parent group "group-id-123" in "master" realm, limit 10

list-group-members ⭐ NOVO

Lista membros de um grupo.

List all members of group "group-id-123" in "master" realm, limit 20

🔗 Ferramentas de Gerenciamento de Provedores de Identidade ⭐ NOVO

create-identity-provider

Cria um novo provedor de identidade para integração SSO.

Create SAML identity provider "company-saml" in "master" realm with SSO URL and certificate

update-identity-provider

Atualiza um provedor de identidade existente.

Update identity provider "company-saml" in "master" realm to change display name

delete-identity-provider

Exclui um provedor de identidade.

Delete identity provider "old-saml" from "master" realm

list-identity-providers

Lista todos os provedores de identidade em um realm.

List all identity providers in "master" realm

get-identity-provider

Obtém detalhes de um provedor de identidade específico.

Get details for identity provider "company-saml" in "master" realm

create-identity-provider-mapper

Cria um mapeador para provedor de identidade (mapeamento de usuário externo).

Create user attribute mapper for identity provider "company-saml" in "master" realm

update-identity-provider-mapper

Atualiza um mapeador de provedor de identidade.

Update mapper "mapper-id-123" for identity provider "company-saml" in "master" realm

📊 Ferramentas de Gerenciamento de Sessões e Eventos

list-sessions

Lista todas as sessões ativas em um realm.

List all active sessions in "master" realm

get-user-sessions

Lista sessões ativas para um usuário específico.

Get active sessions for user "user-id-123" in "master" realm

list-events

Recupera eventos de autenticação e administração.

List last 10 events in "master" realm

clear-events

Limpa logs de eventos.

Clear all events in "master" realm

🧪 Testes e Desenvolvimento

Testes com o MCP Inspector

npx @modelcontextprotocol/inspector npx keycloak-mcp-server

Visite http://localhost:6274 para testar todas as mais de 80 ferramentas interativamente.

Desenvolvimento Local

npm run watch    # Auto-rebuild on changes
npm run dev     # Test server directly

Testes de Estresse

O servidor foi submetido a testes de estresse com mais de 80 operações consecutivas sem falhas de autenticação, demonstrando confiabilidade em nível de produção.

🔧 Arquitetura

Sistema de Autenticação à Prova de Falhas

• Instâncias de Cliente Novas: Cria um novo KcAdminClient para cada solicitação
• Lógica de Repetição: Backoff exponencial com no máximo 2 tentativas
• Gerenciamento de Conexão: Timeout de 15 segundos com limpeza adequada
• Tratamento de Erros: Mensagens de erro abrangentes para todos os cenários

Implementação em TypeScript

• Segurança de Tipos: Cobertura completa de TypeScript com interfaces adequadas
• Tratamento de Erros: Mensagens de erro detalhadas e registro
• Design Modular: Separação clara de responsabilidades

📈 Pronto para Produção

Este pacote foi extensivamente testado e validado:

• ✅ 80+ operações consecutivas sem falhas de autenticação
• ✅ Operações entre realms funcionando perfeitamente
• ✅ Execução paralela de ferramentas suportada
• ✅ Consultas de busca complexas com múltiplos filtros
• ✅ Recuperação de erros e registro detalhado
• ✅ Compilação TypeScript com zero erros
• ✅ Cobertura completa da API do Keycloak com gerenciamento de organizações

🎯 Problema de Organização JWT Resolvido

Este pacote aborda especificamente o problema comum de organização JWT:

• ✅ Atributos de Usuário: Armazene dados de organização em atributos de usuário
• ✅ Mapeadores de Protocolo: Crie mapeadores para incluir organização em tokens JWT
• ✅ Escopos de Cliente: Gerencie escopos de token para declarações de organização
• ✅ Organizações: Gerenciamento completo do ciclo de vida da organização
• ✅ Atributos de Grupo: Armazene metadados de organização em grupos

Exemplo de fluxo de trabalho:

1. Crie uma organização usando create-organization
2. Defina o atributo de organização do usuário usando set-user-attributes
3. Crie um mapeador de protocolo usando create-protocol-mapper para incluir organização no JWT
4. Adicione o usuário à organização usando add-organization-member

🔒 Melhores Práticas de Segurança

• Use variáveis de ambiente para credenciais
• Habilite HTTPS para instâncias de produção do Keycloak
• Use senhas de administrador fortes
• Rotacione credenciais regularmente
• Monitore eventos e sessões de administrador

🤝 Contribuindo

1. Faça um fork do repositório
2. Crie um branch de recurso: git checkout -b feature/amazing-feature
3. Faça commit das alterações: git commit -m 'Add amazing feature'
4. Envie para o branch: git push origin feature/amazing-feature
5. Abra um Pull Request

📄 Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.

🆘 Suporte

• Issues do GitHub: Crie um issue
• Documentação: Consulte este README para exemplos abrangentes
• Documentação MCP: Model Context Protocol

🔗 Projetos Relacionados

• Claude Desktop - assistente de IA com suporte a MCP
• Cursor AI - editor de código com IA e suporte a MCP
• Model Context Protocol - Especificação do protocolo
• Keycloak - Gerenciamento de identidade e acesso de código aberto

📊 Estatísticas do Pacote

• 80+ Ferramentas: Cobertura completa de administração do Keycloak
• Pronto para Produção: Extensivamente testado e validado
• TypeScript: Segurança total de tipos e experiência moderna de desenvolvimento
• Multiplataforma: Suporte para Windows, macOS e Linux
• Zero Problemas de Dependências: Gerenciamento robusto de dependências
• Gerenciamento de Organizações: Resolva problemas de visibilidade de organização JWT
• Recursos Avançados: Mapeadores de protocolo, escopos de cliente, provedores de identidade

---

Feito com ❤️ para a comunidade Keycloak e IA