Octodet Keycloak

Administre o Keycloak gerenciando usuários, realms, funções e outros recursos por meio de uma interface LLM.

GitHub
3
Experimente este MCPPatrocinado

Documentação

Octodet Keycloak MCP Server

npm version License: MIT

Um poderoso servidor Model Context Protocol para administração do Keycloak, fornecendo um conjunto abrangente de ferramentas para gerenciar usuários, realms, papéis e outros recursos do Keycloak por meio de interfaces LLM.

Advanced Keycloak server MCP server

Recursos

  • Gerenciamento de Usuários: Criar, excluir e listar usuários em todos os realms
  • Administração de Realm: Capacidades abrangentes de gerenciamento de realm
  • Integração Segura: Autenticação com credenciais de administrador
  • Configuração Fácil: Configuração simples com variáveis de ambiente
  • Integração com LLM: Uso contínuo com Claude, ChatGPT e outros assistentes de IA compatíveis com MCP

Instalação

Via NPM (Recomendado)

O servidor está disponível como um pacote NPM:

# Direct usage with npx
npx -y @octodet/keycloak-mcp

# Or global installation
npm install -g @octodet/keycloak-mcp

Configuração

Variáveis de Ambiente

VariávelDescriçãoPadrão
KEYCLOAK_URLURL do servidor Keycloakhttp://localhost:8080
KEYCLOAK_ADMINNome de usuário do administradoradmin
KEYCLOAK_ADMIN_PASSWORDSenha do administradoradmin
KEYCLOAK_REALMRealm padrãomaster

Configuração do Cliente MCP

VS Code

Adicione isso ao seu settings.json:

{
  "mcp.servers": {
    "keycloak": {
      "command": "npx",
      "args": ["-y", "@octodet/keycloak-mcp"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

Claude Desktop

Configure no arquivo de configuração do Claude Desktop:

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": ["-y", "@octodet/keycloak-mcp"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

Para Desenvolvimento Local

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": ["path/to/build/index.js"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

Ferramentas Disponíveis

O servidor fornece um conjunto abrangente de ferramentas MCP para administração do Keycloak. Cada ferramenta é projetada para executar tarefas administrativas específicas em realms, usuários e papéis.

📋 Visão Geral das Ferramentas

FerramentaCategoriaDescrição
create-userGerenciamento de UsuáriosCriar um novo usuário em um realm especificado
delete-userGerenciamento de UsuáriosExcluir um usuário existente de um realm
list-usersGerenciamento de UsuáriosListar todos os usuários em um realm especificado
list-realmsGerenciamento de RealmListar todos os realms disponíveis
list-rolesGerenciamento de PapéisListar todos os papéis para um cliente específico
update-user-rolesGerenciamento de PapéisAdicionar ou remover papéis de cliente para um usuário

👥 Gerenciamento de Usuários

create-user

Cria um novo usuário em um realm especificado com atributos abrangentes de usuário e credenciais opcionais.

Parâmetros Obrigatórios:

  • realm (string): Nome do realm de destino
  • username (string): Nome de usuário único para o novo usuário
  • email (string): Endereço de e-mail válido
  • firstName (string): Primeiro nome do usuário
  • lastName (string): Sobrenome do usuário

Parâmetros Opcionais:

  • enabled (boolean): Ativar/desativar conta de usuário (padrão: true)
  • emailVerified (boolean): Marcar e-mail como verificado
  • credentials (array): Matriz de objetos de credencial para definir senhas

Estrutura do Objeto de Credencial:

  • type (string): Tipo de credencial (ex.: "password")
  • value (string): O valor da credencial
  • temporary (boolean): Se a senha deve ser alterada no primeiro login

Exemplo de Uso:

{
  "realm": "my-app-realm",
  "username": "john.doe",
  "email": "john.doe@company.com",
  "firstName": "John",
  "lastName": "Doe",
  "enabled": true,
  "emailVerified": true,
  "credentials": [
    {
      "type": "password",
      "value": "TempPassword123!",
      "temporary": true
    }
  ]
}

Resposta: Retorna o ID do usuário criado e a mensagem de confirmação.

delete-user

Remove permanentemente um usuário do realm especificado. Esta ação não pode ser desfeita.

Parâmetros Obrigatórios:

  • realm (string): Nome do realm de destino
  • userId (string): Identificador único do usuário a ser excluído

Exemplo de Uso:

{
  "realm": "my-app-realm",
  "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c"
}

Resposta: Mensagem de confirmação de exclusão bem-sucedida.

⚠️ Aviso: Esta operação é irreversível. Certifique-se de ter o ID de usuário correto antes da execução.

list-users

Recupera uma lista de todos os usuários no realm especificado com suas informações básicas.

Parâmetros Obrigatórios:

  • realm (string): Nome do realm de destino

Exemplo de Uso:

{
  "realm": "my-app-realm"
}

Resposta: Retorna uma lista formatada mostrando nomes de usuário e IDs de usuário para todos os usuários no realm.

🏛️ Gerenciamento de Realm

list-realms

Recupera todos os realms disponíveis na instância do Keycloak.

Parâmetros: Nenhum obrigatório

Exemplo de Uso:

{}

Resposta: Retorna uma lista de todos os nomes de realm disponíveis na instalação do Keycloak.

Casos de Uso:

  • Descobrir realms disponíveis
  • Validar nomes de realm antes de outras operações
  • Visão geral administrativa da configuração do Keycloak

🔐 Gerenciamento de Papéis

list-roles

Lista todos os papéis definidos para um cliente específico dentro de um realm. Útil para entender as permissões e papéis disponíveis antes da atribuição.

Parâmetros Obrigatórios:

  • realm (string): Nome do realm de destino
  • clientId (string): ID do cliente ou UUID do cliente de destino

Exemplo de Uso:

{
  "realm": "my-app-realm",
  "clientId": "my-application"
}

Alternativa com UUID do Cliente:

{
  "realm": "my-app-realm",
  "clientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Resposta: Retorna uma lista formatada de todos os nomes de papéis disponíveis para o cliente especificado.

💡 Dica: Você pode usar o ID legível do cliente ou seu identificador UUID.

update-user-roles

Gerencia atribuições de papéis de cliente para um usuário. Permite adicionar e remover papéis em uma única operação.

Parâmetros Obrigatórios:

  • realm (string): Nome do realm de destino
  • userId (string): Identificador único do usuário
  • clientId (string): ID do cliente ou UUID

Parâmetros Opcionais:

  • rolesToAdd (array): Lista de nomes de papéis para atribuir ao usuário
  • rolesToRemove (array): Lista de nomes de papéis para remover do usuário

Exemplo de Uso - Adicionando Papéis:

{
  "realm": "my-app-realm",
  "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c",
  "clientId": "my-application",
  "rolesToAdd": ["admin", "user-manager", "report-viewer"]
}

Exemplo de Uso - Removendo Papéis:

{
  "realm": "my-app-realm",
  "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c",
  "clientId": "my-application",
  "rolesToRemove": ["temporary-access", "beta-tester"]
}

Exemplo de Uso - Operação Combinada:

{
  "realm": "my-app-realm",
  "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c",
  "clientId": "my-application",
  "rolesToAdd": ["senior-user"],
  "rolesToRemove": ["junior-user", "trainee"]
}

Resposta: Resumo detalhado dos papéis adicionados, removidos e quaisquer erros encontrados.

🔍 Notas:

  • Pelo menos um de rolesToAdd ou rolesToRemove deve ser fornecido
  • Papéis inexistentes são ignorados com avisos
  • A operação é atômica por lista de papéis (tudo ou nada para cada tipo de operação)

🚀 Dicas de Uso

  1. IDs de Usuário vs Nomes de Usuário: A maioria das operações exige IDs de usuário (UUIDs), não nomes de usuário. Use list-users para encontrar o ID de usuário correto.

  2. Identificação do Cliente: O parâmetro clientId aceita tanto IDs de cliente legíveis quanto identificadores UUID.

  3. Validação de Realm: Sempre verifique os nomes de realm usando list-realms antes de realizar operações.

  4. Descoberta de Papéis: Use list-roles para descobrir papéis disponíveis antes de tentar atribuições de papéis.

  5. Tratamento de Erros: Todas as ferramentas fornecem mensagens de erro detalhadas para solucionar problemas de autenticação, permissão ou parâmetros.

Desenvolvimento

Configurando Seu Ambiente de Desenvolvimento

# Clone the repository
git clone <repository-url>

# Install dependencies
npm install

# Start the development server with watch mode
npm run watch

Adicionando Novas Ferramentas

Para adicionar uma nova ferramenta ao servidor:

  1. Defina o esquema da ferramenta em src/index.ts usando Zod
  2. Adicione a definição da ferramenta ao manipulador ListToolsRequestSchema
  3. Implemente o manipulador da ferramenta na instrução switch CallToolRequestSchema
  4. Atualize este README para documentar a nova ferramenta

Testes

Usando o MCP Inspector

O MCP Inspector é uma ótima ferramenta para testar seu servidor MCP:

npx -y @modelcontextprotocol/inspector npx -y @octodet/keycloak-mcp

Testes de Integração

Para testar com uma instância local do Keycloak:

# Start Keycloak with Docker
docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev

# In another terminal, run the MCP server
npm run build
node build/index.js

Implantação

Pacote NPM

Este projeto é publicado no NPM sob @octodet/keycloak-mcp.

Implantação Automatizada

Este projeto usa GitHub Actions para CI/CD para testar e publicar automaticamente no NPM quando uma nova versão é criada.

Pré-requisitos

  • Node.js 18 ou superior
  • Instância do Keycloak em execução

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Autor

Octodet - Construindo ferramentas inteligentes para desenvolvedores