Keycloak MCP Server

Um servidor completo do Model Context Protocol (MCP) para o Keycloak 26.x

Documentação

Keycloak MCP Server

Um servidor abrangente de Model Context Protocol (MCP) que expõe a Keycloak Admin REST API como ferramentas MCP tipadas. 299 ferramentas cobrindo todas as categorias da API.

Recursos

Cobertura completa da API: Todos os 299 endpoints da Keycloak Admin REST API
Transporte duplo: stdio (Claude Code) e SSE (GitHub Copilot, outros clientes MCP)
Autenticação automática: Suporta fluxos de senha e credenciais de cliente com renovação automática de token
Ferramentas sem configuração: Cada ferramenta é autodescritiva com esquemas de entrada completos

Categorias da API

Categoria	Ferramentas
Detecção de Ataques	3
Gerenciamento de Autenticação	38
Certificados de Cliente	6
Acesso Inicial do Cliente	3
Política de Registro de Cliente	1
Mapeamentos de Papéis do Cliente	10
Escopos de Cliente	10
Clientes	33
Componentes	6
Grupos	11
Provedores de Identidade	15
Chaves	2
Organizações	13
Mapeadores de Protocolo	14
Administração de Realms	37
Papéis	28
Papéis por ID	10
Mapeamentos de Escopo	29
Usuários	30
Total	299

Demonstração

(Adicione um GIF ou captura de tela aqui demonstrando 3 prompts reais e suas ferramentas executadas!)

Instalação

Opção 1: Executar diretamente com `uvx` (Recomendado)

Você pode executar o servidor diretamente sem instalação manual usando o uv da astral:

uvx keycloak-mcp-server

(Ao usar uvx, você pode passar variáveis de ambiente inline ou mantê-las no seu arquivo de configuração MCP.)

Opção 2: Instalar via pip

Se você preferir uma instalação global ou em ambiente virtual:

pip install git+https://github.com/paoloamato2/keycloak-mcp-server.git

Opção 3: Instalar a partir do código-fonte (Para desenvolvimento)

git clone https://github.com/paoloamato2/keycloak-mcp-server.git
cd keycloak-mcp-server
uv pip install -e .

Configuração

Defina as variáveis de ambiente (ou crie um arquivo .env baseado em .env.example):

# Required
export KEYCLOAK_URL=http://localhost:8080

# Authentication - Option A: Password flow
export KEYCLOAK_ADMIN_USERNAME=admin
export KEYCLOAK_ADMIN_PASSWORD=admin

# Authentication - Option B: Client credentials flow
export KEYCLOAK_CLIENT_ID=my-client
export KEYCLOAK_CLIENT_SECRET=my-secret

# Optional
export KEYCLOAK_ADMIN_REALM=master    # default: master
export KEYCLOAK_VERIFY_SSL=true       # default: true

Uso

Claude Code (stdio)

Adicione à sua configuração MCP do Claude Code (~/.claude/claude_desktop_config.json ou nível de projeto):

{
  "mcpServers": {
    "keycloak": {
      "command": "python",
      "args": ["-m", "keycloak_mcp_server"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN_USERNAME": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

Ou se instalado com uv:

{
  "mcpServers": {
    "keycloak": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/keycloak-mcp-server", "python", "-m", "keycloak_mcp_server"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN_USERNAME": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

GitHub Copilot (SSE)

Inicie o servidor com transporte SSE:

python -m keycloak_mcp_server --transport sse --port 8080

Em seguida, configure nas configurações MCP do seu GitHub Copilot (VS Code settings.json):

{
  "github.copilot.chat.mcpServers": {
    "keycloak": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

Linha de Comando

# stdio mode (default)
python -m keycloak_mcp_server

# SSE mode
python -m keycloak_mcp_server --transport sse --host 0.0.0.0 --port 8080

# Using the entry point
keycloak-mcp-server --transport sse --port 8080

Recomendações de Segurança e Produção

⚠️ AVISO DE SEGURANÇA: Este MCP Server registra todos os endpoints da Keycloak Admin REST API (299 ferramentas), incluindo operações de escrita sensíveis (como criar/excluir usuários, redefinir senhas e gerenciar realms). Não use suas credenciais de superadministrador do realm master em um ambiente de produção.

Ao anexar este servidor MCP aos seus Assistentes de IA, siga estritamente o Princípio do Menor Privilégio:

Use Contas de Serviço (Fluxo de Credenciais de Cliente): Evite usar o fluxo de Senha (KEYCLOAK_ADMIN_USERNAME / KEYCLOAK_ADMIN_PASSWORD). Em vez disso, crie um Cliente Keycloak dedicado com Contas de Serviço Habilitadas e use o KEYCLOAK_CLIENT_ID e o KEYCLOAK_CLIENT_SECRET.
Limite os Realms Alvo: Não anexe o servidor ao realm master a menos que seja especificamente necessário. Aponte KEYCLOAK_ADMIN_REALM para o realm exato que seu assistente de IA deve gerenciar.
Conceda Apenas os Papéis Necessários: Atribua apenas os papéis mínimos necessários à sua Conta de Serviço MCP.
- Se seu LLM só precisa ler dados: Atribua apenas view-users, view-clients ou view-realm.
- Se seu LLM precisa gerenciar usuários: Atribua apenas manage-users.
- Nunca atribua papéis de admin ou realm-admin à IA, a menos que você esteja totalmente ciente dos riscos.
Sempre Verifique SSL: Mantenha KEYCLOAK_VERIFY_SSL=true habilitado em produção para prevenir ataques Man-in-the-Middle (MITM). Definir como false só é aceitável para desenvolvimento local.

Exemplos

Uma vez conectado, você pode usar linguagem natural para interagir com o Keycloak:

"Liste todos os realms" → chama list_realms
"Crie um usuário chamado john no realm master" → chama create_user
"Mostre-me todos os clientes no realm de produção" → chama list_clients
"Quais papéis o usuário X possui?" → chama get_user_role_mappings
"Adicione o papel admin ao grupo de desenvolvedores" → chama add_group_realm_role_mappings

Estrutura do Projeto

src/keycloak_mcp_server/
├── __init__.py          # Package entry point
├── __main__.py          # CLI entry point
├── config.py            # Environment-based configuration
├── client.py            # Async HTTP client with auto-auth
├── server.py            # MCP server setup and tool registration
└── endpoints/           # Endpoint definitions by category
    ├── __init__.py      # Base classes (EndpointDef, Param)
    ├── attack_detection.py
    ├── authentication.py
    ├── certificates.py
    ├── client_initial_access.py
    ├── client_registration_policy.py
    ├── client_role_mappings.py
    ├── client_scopes.py
    ├── clients.py
    ├── component.py
    ├── groups.py
    ├── identity_providers.py
    ├── key.py
    ├── organizations.py
    ├── protocol_mappers.py
    ├── realms.py
    ├── roles.py
    ├── roles_by_id.py
    ├── scope_mappings.py
    └── users.py

Licença

MIT

Keycloak MCP Server

Documentação