aelkz/another-keycloak-mcp

AKC-MCP (Another Keycloak MCP)

A comprehensive Model Context Protocol (MCP) server for Keycloak IAM with advanced user management capabilities and built-in safety features.

For installation and setup instructions, see

Overview

AKC-MCP provides a complete MCP interface to Keycloak, enabling AI assistants like Claude to manage Identity and Access Management operations safely and efficiently. Built with TypeScript and the official Keycloak Admin Client, it offers 45 tools across user management, group management, realm operations, authentication flows, and client scopes.

Key Features

• 🔍 Advanced User Search: Multi-field search with exact/fuzzy matching, duplicate detection, IDP link checking
• 👥 Comprehensive Group Management: Full CRUD with attribute management, hierarchy navigation, boolean flags
• 🌐 Realm Operations: Export, statistics, SAML certificate monitoring, custom SPI detection
• 🔐 Authentication Management: Flow inspection, required actions, configuration analysis
• 🎯 Client Scope Management: Full CRUD operations for OIDC and SAML scopes
• 🛡️ Safety Features: Development/Production modes, read-only mode, operation warnings
• 📝 Type Safety: Full TypeScript with Zod runtime validation
• 🔌 Dual Transport: Stdio (MCP) and HTTP/SSE support

Designed For

• Keycloak administrators and DevOps teams
• Identity and Access Management automation
• Bulk user operations and auditing
• Realm configuration management
• Security compliance monitoring
• Development and testing workflows

Available Tools (45 Total)

User Management (13 tools)

Advanced user lookup and management with safety checks.

Group Management (16 tools)

Complete group lifecycle management with attribute support.

Realm Operations (6 tools)

Realm configuration, statistics, and management.

Authentication (3 tools)

Authentication flow and required action management.

Client Scopes (7 tools)

OIDC and SAML client scope management.

Safety Features

Operation Modes

Development Mode (default)

• Write operations allowed with warnings
• Full error stack traces for debugging
• Verbose logging available

Production Mode

OPERATION_MODE=production

• Additional confirmations for write operations
• Enhanced warnings for destructive operations
• Sanitized error messages

Read-Only Mode

READ_ONLY_MODE=true

• Blocks all write operations (create, update, delete)
• Perfect for auditing and inspection
• Safe for production environments
• Ideal for learning and exploration

Safety Checks

All write operations include:

• ✅ Operation mode validation
• ✅ Read-only mode enforcement
• ✅ Destructive operation warnings
• ✅ Structured logging
• ✅ Safety warning messages in responses

Architecture

Technology Stack

• Language: TypeScript with strict mode
• Runtime: Node.js 18+
• Keycloak Client: Official @keycloak/keycloak-admin-client v26.x
• MCP SDK: @modelcontextprotocol/sdk
• Validation: Zod schemas for runtime type checking
• Logging: Winston structured logging
• Build: tsup for efficient ESM bundling

Project Structure

src/
├── common/              # Server setup, constants
├── config/              # Environment-based configuration
├── schemas/             # Zod validation schemas
├── services/            # Keycloak client wrapper
├── tools/               # MCP tool implementations
│   ├── user-tools.ts              (13 tools)
│   ├── group-tools.ts             (16 tools)
│   ├── realm-operations.ts        (3 tools)
│   ├── realm-tools.ts             (3 tools)
│   ├── authentication-tools.ts    (3 tools)
│   └── client-scope-tools.ts      (7 tools)
├── types/               # TypeScript definitions
├── utils/               # Logger, safety checks
└── index.ts             # Main entry point

Quick Start

Prerequisites

• Node.js 18+
• Keycloak server running (v26.4.5 recommended)
• Keycloak admin credentials

Installation

npm install -g another-keycloak-mcp

Basic Configuration

# Create .env file
cat > .env << EOF
KEYCLOAK_URL=http://0.0.0.0:8082
KEYCLOAK_REALM=master
KEYCLOAK_ADMIN_USERNAME=admin
KEYCLOAK_ADMIN_PASSWORD=admin
EOF

# Run
akc-mcp

For complete setup instructions, see

Use Cases

User Management

• Bulk user creation and updates
• Duplicate email detection and cleanup
• Identity provider link verification
• Session monitoring and management
• User attribute auditing

Group Management

• Dynamic group organization
• Feature flag management via boolean attributes
• Group hierarchy navigation
• Bulk membership operations
• Attribute-based group filtering

Realm Operations

• Configuration backup and export
• SAML certificate expiration monitoring
• Custom SPI inventory
• Multi-realm statistics collection
• Realm configuration analysis

Authentication

• Flow configuration inspection
• Required action management
• Authentication method auditing
• Login flow analysis

Client Scopes

• Scope template management
• Bulk scope assignment
• OIDC/SAML configuration
• Protocol mapper analysis

Example Usage

Search for Users

{
  "tool": "search-user",
  "arguments": {
    "realm": "master",
    "email": "@example.com",
    "exact": false
  }
}

Check Identity Provider Links

{
  "tool": "check-user-idp-broker-link",
  "arguments": {
    "realm": "master",
    "userId": "user-id-here",
    "identityProvider": "google"
  }
}

Search Groups by Attribute

{
  "tool": "search-groups-by-attributes",
  "arguments": {
    "realm": "master",
    "attributeKey": "feature_flag",
    "attributeValue": "true",
    "exact": true
  }
}

Export Realm Configuration

{
  "tool": "export-realm",
  "arguments": {
    "realm": "master",
    "includeUsers": false,
    "includeGroups": true,
    "includeRoles": true,
    "includeClients": true
  }
}

Monitor SAML Certificates

{
  "tool": "check-saml-certificates",
  "arguments": {
    "realm": "production",
    "warnDays": 30
  }
}

Documentation

• - Installation, configuration, and deployment

Version Compatibility

• Keycloak: Tested with version 26.4.5
• Node.js: Requires version 18 or higher
• MCP Protocol: Version 1.0

Note: While this server is designed for Keycloak 26.4.5, it may work with other versions. Some features might behave differently with version mismatches.

License

MIT License - see file for details

Acknowledgments

• Built with Model Context Protocol SDK
• Uses Keycloak Admin Client
• Inspired by the Keycloak community and existing MCP implementations