The Keycloak MCP Server provides a natural language interface for managing Keycloak identity and access management through its REST API, enabling AI agents to automate comprehensive identity operations.
Core Capabilities:
User Management: Create, read, update, and delete users; reset passwords; manage user sessions and logout capabilities; retrieve user statistics and counts
Client Configuration: Full CRUD operations for OAuth2/OIDC clients; manage client secrets and regeneration; handle service accounts
Role-Based Access Control: Define and manage realm-level and client-specific roles; assign/remove roles to/from users; retrieve user role assignments
Group Management: Organize users into groups with hierarchical structures; manage group memberships and retrieve user group associations
Realm Administration: Configure realm settings including display name, themes, registration policies, password policies, SSL requirements, and brute force protection; manage realm events and default groups
Session Management: Handle user session logistics including logging out specific users or clearing all realm sessions
Integration Benefits:
Automation: Enable automated user provisioning and identity analytics through natural language commands
DevOps Integration: Integrate Keycloak management into CI/CD pipelines for automated identity service configuration
Provides comprehensive identity and access management capabilities through Keycloak's REST API, enabling user lifecycle management, OAuth2/OIDC client configuration, role-based access control, realm administration, and group management operations.
Keycloak MCP Server
A Model Context Protocol (MCP) server that provides a natural language interface for managing Keycloak identity and access management through its REST API. This server enables AI agents to perform user management, client configuration, realm administration, and role-based access control operations seamlessly.
Overview
The Keycloak MCP Server bridges the gap between AI applications and Keycloak's powerful identity management capabilities. Whether you're building an AI assistant that needs to manage users, configure clients, or handle complex authorization scenarios, this server provides the tools you need through simple, natural language commands.
Features
🔐 Comprehensive User Management
Manage users lifecycle from creation to deletion, including password resets, session management, and user attribute updates.
🏢 Client Configuration
Create and configure OAuth2/OIDC clients, manage client secrets, and handle service accounts programmatically.
👥 Role-Based Access Control
Define and assign realm and client-specific roles, manage user permissions, and implement fine-grained access control.
🏛️ Realm Administration
Configure realm settings, manage default groups, handle event configurations, and control realm-wide policies.
🔐 Authentication Management
Comprehensive authentication flow management including creating, updating, and deleting flows, managing executions, and configuring authenticators.
🔄 Group Management
Organize users into groups, manage group hierarchies, and handle group-based permissions efficiently.
Installation
Installing via Smithery
To install mcp-keycloak for Claude Desktop automatically via Smithery:
Quick Start
Install using pip:
Development Installation
Clone the repository and install dependencies:
Configuration
The server can be configured using environment variables or a .env
file:
Tools
The Keycloak MCP Server provides a comprehensive set of tools organized by functionality:
User Management
Complete user lifecycle management including:
list_users
- List users with pagination and filteringcreate_user
/update_user
/delete_user
- Full CRUD operationsreset_user_password
- Password managementget_user_sessions
/logout_user
- Session controlcount_users
- User statistics
Client Management
OAuth2/OIDC client configuration:
list_clients
/get_client
/create_client
- Client operationsget_client_secret
/regenerate_client_secret
- Secret managementget_client_service_account
- Service account accessupdate_client
/delete_client
- Client modifications
Role Management
Fine-grained permission control:
list_realm_roles
/create_realm_role
- Realm role operationslist_client_roles
/create_client_role
- Client-specific rolesassign_realm_role_to_user
/remove_realm_role_from_user
- Role assignmentsget_user_realm_roles
/assign_client_role_to_user
- User role queries
Group Management
Hierarchical user organization:
list_groups
/create_group
/update_group
- Group operationsget_group_members
/add_user_to_group
- Membership managementget_user_groups
/remove_user_from_group
- User group associations
Realm Administration
System-wide configuration:
get_accessible_realms
- List of accessible realmsget_realm_info
/update_realm_settings
- Realm configurationget_realm_events_config
/update_realm_events_config
- Event managementadd_realm_default_group
/remove_realm_default_group
- Default settings
Authentication Management
Complete authentication flow control:
list_authentication_flows
/get_authentication_flow
- Flow managementcreate_authentication_flow
/update_authentication_flow
- Flow CRUD operationsdelete_authentication_flow
/copy_authentication_flow
- Flow modificationsget_flow_executions
/update_flow_executions
- Execution managementcreate_execution
/delete_execution
- Execution lifecycleget_authenticator_config
/create_authenticator_config
- Configuration managementget_required_actions
/update_required_action
- Required actions control
Usage
Running the Server
The server supports both stdio (default) and HTTP transports. The smithery.yaml configuration file enables deployment on the Smithery platform and automatic installation via Smithery CLI:
When using HTTP transport, the server will be accessible at http://127.0.0.1:8000/mcp/
(or your custom PORT).
HTTP Transport
The Keycloak MCP Server supports HTTP transport mode, which offers several advantages:
- Network Accessibility: Access the server from any machine on your network
- Multiple Clients: Support concurrent connections from multiple AI clients
- Integration Flexibility: Easy integration with web applications and APIs
- Load Balancing: Deploy behind a reverse proxy for scalability
HTTP Protocol Details
The HTTP transport follows the MCP specification for Streamable HTTP. FastMCP automatically handles all protocol requirements:
- Endpoint: All communication happens through
/mcp/
endpoint - Request Method: POST requests with JSON-RPC 2.0 messages
- Content Types:
- Server returns
Content-Type: application/json
for single responses - Server returns
Content-Type: text/event-stream
for streaming responses
- Server returns
- Accept Headers: Clients must include
Accept: application/json, text/event-stream
- Message Format: All messages use JSON-RPC 2.0 format, UTF-8 encoded
FastMCP automatically determines whether to return a single JSON response or an SSE stream based on the request type and whether the response needs streaming capabilities.
Connecting to HTTP Server
When running in HTTP mode, clients can connect to:
Example client request:
Security Implementation
The HTTP transport implements all MCP specification security requirements:
✅ Origin Header Validation (REQUIRED)
- Automatically validates Origin headers to prevent DNS rebinding attacks
- Only allows connections from
localhost
and127.0.0.1
origins - Blocks unauthorized cross-origin requests
✅ Localhost Binding (RECOMMENDED)
- Binds to
127.0.0.1
only to prevent network-based attacks - Follows MCP specification security recommendations
✅ No Authentication Required
- The server runs without authentication requirements for simplified local development
- Suitable for localhost usage and trusted environments
For production deployments, additional considerations:
- Use HTTPS with proper certificates
- Deploy behind a reverse proxy (nginx, Apache)
- Set appropriate firewall rules
- Implement authentication at the reverse proxy level if needed
Integration Examples
Prerequisites
Before integrating the Keycloak MCP Server, ensure you have one of the following installed:
- uvx (recommended): Install via
pip install uvx
orpipx install uvx
- uv: Follow installation instructions
- npm/npx: For Smithery installation (comes with Node.js)
Option 1: Using Smithery CLI (Recommended)
The easiest way - automatically configures everything for Claude Desktop:
This command will prompt you for the required configuration values and set up the server automatically.
Option 2: Using uvx (Manual Setup)
No cloning required! Add to your claude_desktop_config.json
:
Option 3: Local Development Setup
For development or customization:
- Clone the repository:
- Add to your
claude_desktop_config.json
:
💡 Quick Tips:
- Replace
/path/to/mcp-keycloak
with the actual path where you cloned the repository - Ensure your Keycloak server URL includes the protocol (
https://
orhttp://
) - The
REALM_NAME
should match an existing realm in your Keycloak instance
Example Use Cases
🤖 AI-Powered Identity Management
Build AI assistants that can handle user onboarding, permission management, and access control through natural language commands.
🔄 Automated User Provisioning
Create workflows that automatically provision users, assign roles, and configure client applications based on business rules.
📊 Identity Analytics
Query and analyze user data, session information, and access patterns to gain insights into your identity infrastructure.
🚀 DevOps Integration
Integrate Keycloak management into your CI/CD pipelines, allowing automated configuration of identity services.
Requirements
- Python 3.8 or higher
- Keycloak server (tested with Keycloak 18+)
- Admin access to Keycloak realm
License
This project is licensed under the MIT License - see the LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Support
For issues, questions, or contributions, please visit the GitHub repository.
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
Managing Keycloak identity and access management
Related MCP Servers
- MIT License
- GPL 3.0