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 SETUP.md

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.

• 🔍 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

• 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

Advanced user lookup and management with safety checks.

Complete group lifecycle management with attribute support.

Realm configuration, statistics, and management.

Authentication flow and required action management.

OIDC and SAML client scope management.

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=true

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

All write operations include:

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

• 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

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

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

npm install -g another-keycloak-mcp

# 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 SETUP.md

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

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

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

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

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

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

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

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

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

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

• SETUP.md - Installation, configuration, and deployment

• 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.

MIT License - see LICENSE file for details

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