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.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-keycloak list all users in the marketing realm"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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.
Related MCP server: Advanced Keycloak MCP server
Manage users lifecycle from creation to deletion, including password resets, session management, and user attribute updates.
Create and configure OAuth2/OIDC clients, manage client secrets, and handle service accounts programmatically.
Define and assign realm and client-specific roles, manage user permissions, and implement fine-grained access control.
Configure realm settings, manage default groups, handle event configurations, and control realm-wide policies.
Comprehensive authentication flow management including creating, updating, and deleting flows, managing executions, and configuring authenticators.
Organize users into groups, manage group hierarchies, and handle group-based permissions efficiently.
To install mcp-keycloak for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install mcp-keycloak --client claudeInstall using pip:
pip install mcp-keycloakClone the repository and install dependencies:
git clone https://github.com/idoyudha/mcp-keycloak.git
cd mcp-keycloak
pip install -e .The server can be configured using environment variables or a .env file:
# Required configuration
SERVER_URL=https://your-keycloak-server.com
USERNAME=admin-username
PASSWORD=admin-password
REALM_NAME=your-realm
# Optional OAuth2 client configuration
CLIENT_ID=optional-client-id
CLIENT_SECRET=optional-client-secretThe Keycloak MCP Server provides a comprehensive set of tools organized by functionality:
Complete user lifecycle management including:
list_users - List users with pagination and filtering
create_user / update_user / delete_user - Full CRUD operations
reset_user_password - Password management
get_user_sessions / logout_user - Session control
count_users - User statistics
OAuth2/OIDC client configuration:
list_clients / get_client / create_client - Client operations
get_client_secret / regenerate_client_secret - Secret management
get_client_service_account - Service account access
update_client / delete_client - Client modifications
Fine-grained permission control:
list_realm_roles / create_realm_role - Realm role operations
list_client_roles / create_client_role - Client-specific roles
assign_realm_role_to_user / remove_realm_role_from_user - Role assignments
get_user_realm_roles / assign_client_role_to_user - User role queries
Hierarchical user organization:
list_groups / create_group / update_group - Group operations
get_group_members / add_user_to_group - Membership management
get_user_groups / remove_user_from_group - User group associations
System-wide configuration:
get_accessible_realms - List of accessible realms
get_realm_info / update_realm_settings - Realm configuration
get_realm_events_config / update_realm_events_config - Event management
add_realm_default_group / remove_realm_default_group - Default settings
Complete authentication flow control:
list_authentication_flows / get_authentication_flow - Flow management
create_authentication_flow / update_authentication_flow - Flow CRUD operations
delete_authentication_flow / copy_authentication_flow - Flow modifications
get_flow_executions / update_flow_executions - Execution management
create_execution / delete_execution - Execution lifecycle
get_authenticator_config / create_authenticator_config - Configuration management
get_required_actions / update_required_action - Required actions control
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:
# Run in stdio mode (default, for local CLI tools)
python -m src.main
# Run in HTTP mode with streamable HTTP transport
TRANSPORT=http python -m src.main
# Run HTTP mode on a custom port
TRANSPORT=http PORT=8080 python -m src.main
# Or use the convenience script:
./scripts/run_server.sh # stdio mode (default)
./scripts/run_server.sh http # HTTP mode
PORT=8080 ./scripts/run_server.sh http # HTTP mode on custom portWhen using HTTP transport, the server will be accessible at http://127.0.0.1:8000/mcp/ (or your custom PORT).
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
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
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.
When running in HTTP mode, clients can connect to:
http://127.0.0.1:8000/mcp/Example client request:
curl -X POST http://localhost:8000/mcp/ \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc": "2.0", "method": "list_tools", "id": 1}'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 and 127.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
Before integrating the Keycloak MCP Server, ensure you have one of the following installed:
uvx (recommended): Install via pip install uvx or pipx install uvx
uv: Follow installation instructions
npm/npx: For Smithery installation (comes with Node.js)
The easiest way - automatically configures everything for Claude Desktop:
npx @smithery/cli install @idoyudha/mcp-keycloak --client claudeThis command will prompt you for the required configuration values and set up the server automatically.
No cloning required! Add to your claude_desktop_config.json:
{
"mcpServers": {
"keycloak": {
"command": "uvx",
"args": ["mcp-keycloak"],
"env": {
"SERVER_URL": "https://your-keycloak.com",
"USERNAME": "admin",
"PASSWORD": "admin-password",
"REALM_NAME": "your-realm"
}
}
}
}For development or customization:
Clone the repository:
git clone https://github.com/idoyudha/mcp-keycloak.git
cd mcp-keycloakAdd to your claude_desktop_config.json:
{
"mcpServers": {
"keycloak": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp-keycloak",
"run",
"python",
"-m",
"src"
],
"env": {
"SERVER_URL": "https://your-keycloak.com",
"USERNAME": "admin",
"PASSWORD": "admin-password",
"REALM_NAME": "your-realm"
}
}
}
}💡 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:// or http://)
The REALM_NAME should match an existing realm in your Keycloak instance
Build AI assistants that can handle user onboarding, permission management, and access control through natural language commands.
Create workflows that automatically provision users, assign roles, and configure client applications based on business rules.
Query and analyze user data, session information, and access patterns to gain insights into your identity infrastructure.
Integrate Keycloak management into your CI/CD pipelines, allowing automated configuration of identity services.
Python 3.8 or higher
Keycloak server (tested with Keycloak 18+)
Admin access to Keycloak realm
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.
For issues, questions, or contributions, please visit the GitHub repository.
Add a default group to the realm.
Args:
group_id: Group ID to add as default
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: group_id (required), realm. Returns: result
Add a user to a group.
Args:
user_id: User ID
group_id: Group ID
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: user_id (required), group_id (required), realm. Returns: result
Assign client roles to a user.
Args:
user_id: User ID
client_id: Client database ID
role_names: List of role names to assign
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: user_id (required), client_id (required), role_names (required), realm. Returns: result
Assign realm roles to a user.
Args:
user_id: User ID
role_names: List of role names to assign
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: user_id (required), role_names (required), realm. Returns: result
Count all users.
Args:
realm: Target realm (uses default if not specified)
Returns:
Number of users
Inputs: realm. Returns: result
Create a new client.
Args:
client_id: Client ID (unique identifier)
name: Display name
description: Client description
enabled: Whether the client is enabled
always_display_in_console: Always display in account console
root_url: Root URL for relative URLs
redirect_uris: Valid redirect URIs
web_origins: Allowed CORS origins
protocol: Protocol (openid-connect or saml)
public_client: Public client (no secret)
bearer_only: Bearer-only client
service_accounts_enabled: Enable service accounts
authorization_services_enabled: Enable authorization services
direct_access_grants_enabled: Enable direct access grants (password flow)
implicit_flow_enabled: Enable implicit flow
standard_flow_enabled: Enable standard flow (authorization code)
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: client_id (required), name, description, enabled, +13 more. Returns: result
Create a new client role.
Args:
client_id: Client database ID
name: Role name
description: Role description
composite: Whether this is a composite role
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: client_id (required), name (required), description, composite, +1 more. Returns: result
Create a new group.
Args:
name: Group name
path: Group path
attributes: Group attributes
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: name (required), path, attributes, realm. Returns: result
Create a new realm role.
Args:
name: Role name
description: Role description
composite: Whether this is a composite role
client_role: Whether this is a client role
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: name (required), description, composite, client_role, +1 more. Returns: result
Create a new user.
Args:
username: Username for the new user
email: Email address
first_name: First name
last_name: Last name
enabled: Whether the user is enabled
email_verified: Whether the email is verified
temporary_password: Initial password (user will be required to change it)
attributes: Additional user attributes
realm: Target realm (uses default if not specified)
Returns:
Dict with status and location of created user
Inputs: username (required), email, first_name, last_name, +5 more. Returns: result
Delete a client.
Args:
id: The client's database ID
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: id (required), realm. Returns: result
Delete a group.
Args:
group_id: Group ID
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: group_id (required), realm. Returns: result
Delete a realm role.
Args:
role_name: Role name to delete
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: role_name (required), realm. Returns: result
Delete a user.
Args:
user_id: The user's ID
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: user_id (required), realm. Returns: result
Get accessible realms.
Returns:
List of accessible realms
Inputs: no named parameters. Returns: result
Get a specific client by database ID.
Args:
id: The client's database ID (not client_id)
realm: Target realm (uses default if not specified)
Returns:
Client object
Inputs: id (required), realm. Returns: result
Get a specific client by client ID.
Args:
client_id: The client's client_id
realm: Target realm (uses default if not specified)
Returns:
Client object
Inputs: client_id (required), realm. Returns: result
Get the client secret.
Args:
id: The client's database ID
realm: Target realm (uses default if not specified)
Returns:
Client secret object
Inputs: id (required), realm. Returns: result
Get service account user for a client.
Args:
id: The client's database ID
realm: Target realm (uses default if not specified)
Returns:
Service account user object
Inputs: id (required), realm. Returns: result
Get a specific group by ID.
Args:
group_id: Group ID
realm: Target realm (uses default if not specified)
Returns:
Group object
Inputs: group_id (required), realm. Returns: result
Get members of a group.
Args:
group_id: Group ID
first: Pagination offset
max: Maximum results size
realm: Target realm (uses default if not specified)
Returns:
List of group members
Inputs: group_id (required), first, max, realm. Returns: result
Get default groups for the realm.
Args:
realm: Target realm (uses default if not specified)
Returns:
List of default groups
Inputs: realm. Returns: result
Get realm events configuration.
Args:
realm: Target realm (uses default if not specified)
Returns:
Events configuration object
Inputs: realm. Returns: result
Get information about the current realm.
Args:
realm: Target realm (uses default if not specified)
Returns:
Realm configuration object
Inputs: realm. Returns: result
Get a specific realm role by name.
Args:
role_name: Role name
realm: Target realm (uses default if not specified)
Returns:
Role object
Inputs: role_name (required), realm. Returns: result
Get a specific user by ID.
Args:
user_id: The user's ID
realm: Target realm (uses default if not specified)
Returns:
User object
Inputs: user_id (required), realm. Returns: result
Get all groups for a user.
Args:
user_id: User ID
realm: Target realm (uses default if not specified)
Returns:
List of groups the user belongs to
Inputs: user_id (required), realm. Returns: result
Get realm roles for a user.
Args:
user_id: User ID
effective: Get effective roles (including composite roles)
realm: Target realm (uses default if not specified)
Returns:
List of realm roles
Inputs: user_id (required), effective, realm. Returns: result
Get active sessions for a user.
Args:
user_id: The user's ID
realm: Target realm (uses default if not specified)
Returns:
List of active sessions
Inputs: user_id (required), realm. Returns: result
List roles for a specific client.
Args:
client_id: Client database ID
first: Pagination offset
max: Maximum results size
search: Search string
realm: Target realm (uses default if not specified)
Returns:
List of client roles
Inputs: client_id (required), first, max, search, +1 more. Returns: result
List clients in the realm.
Args:
client_id: Filter by client ID (partial match)
viewable_only: Only return viewable clients
first: Pagination offset
max: Maximum results size
realm: Target realm (uses default if not specified)
Returns:
List of client objects
Inputs: client_id, viewable_only, first, max, +1 more. Returns: result
List all groups in the realm.
Args:
first: Pagination offset
max: Maximum results size
search: Search string
realm: Target realm (uses default if not specified)
Returns:
List of groups
Inputs: first, max, search, realm. Returns: result
List all realm roles.
Args:
first: Pagination offset
max: Maximum results size
search: Search string
realm: Target realm (uses default if not specified)
Returns:
List of realm roles
Inputs: first, max, search, realm. Returns: result
List users in the realm.
Args:
first: Pagination offset
max: Maximum results size (defaults to 100)
search: Search string for username, first/last name, or email
username: Username filter
email: Email filter
enabled: Filter by enabled/disabled users
realm: Target realm (uses default if not specified)
Returns:
List of user objects
Inputs: first, max, search, username, +3 more. Returns: result
Logout all sessions for a user.
Args:
user_id: The user's ID
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: user_id (required), realm. Returns: result
Regenerate the client secret.
Args:
id: The client's database ID
realm: Target realm (uses default if not specified)
Returns:
New client secret object
Inputs: id (required), realm. Returns: result
Remove all sessions for all users in the realm.
Args:
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: realm. Returns: result
Remove a default group from the realm.
Args:
group_id: Group ID to remove from defaults
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: group_id (required), realm. Returns: result
Remove realm roles from a user.
Args:
user_id: User ID
role_names: List of role names to remove
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: user_id (required), role_names (required), realm. Returns: result
Remove a user from a group.
Args:
user_id: User ID
group_id: Group ID
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: user_id (required), group_id (required), realm. Returns: result
Reset a user's password.
Args:
user_id: The user's ID
password: New password
temporary: Whether the password is temporary (user must change on next login)
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: user_id (required), password (required), temporary, realm. Returns: result
Update an existing client.
Args:
id: The client's database ID
client_id: New client ID
name: New display name
description: New description
enabled: Whether the client is enabled
redirect_uris: New redirect URIs
web_origins: New CORS origins
public_client: Whether client is public
service_accounts_enabled: Enable service accounts
direct_access_grants_enabled: Enable direct access grants
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: id (required), client_id, name, description, +7 more. Returns: result
Update a group.
Args:
group_id: Group ID
name: New group name
path: New group path
attributes: New group attributes
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: group_id (required), name, path, attributes, +1 more. Returns: result
Update realm events configuration.
Args:
events_enabled: Enable events
events_listeners: Event listener implementations
enabled_event_types: Types of events to record
admin_events_enabled: Enable admin events
admin_events_details_enabled: Include details in admin events
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: events_enabled, events_listeners, enabled_event_types, admin_events_enabled, +2 more. Returns: result
Update a realm role.
Args:
role_name: Current role name
description: New description
composite: Whether this is a composite role
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: role_name (required), description, composite, realm. Returns: result
Update realm settings.
Args:
display_name: Display name for the realm
display_name_html: HTML display name
login_theme: Login theme name
account_theme: Account management theme
admin_theme: Admin console theme
email_theme: Email theme
enabled: Whether realm is enabled
registration_allowed: Allow user registration
registration_email_as_username: Use email as username
reset_password_allowed: Allow password reset
remember_me: Enable remember me
verify_email: Require email verification
login_with_email_allowed: Allow login with email
duplicate_emails_allowed: Allow duplicate emails
ssl_required: SSL requirement (none, external, all)
brute_force_protected: Enable brute force protection
permanent_lockout: Permanent lockout on max failures
max_failure_wait_seconds: Max wait after failures
minimum_quick_login_wait_seconds: Min wait between quick logins
wait_increment_seconds: Wait increment
quick_login_check_milli_seconds: Quick login check interval
max_delta_time_seconds: Max time between failures
failure_factor: Failure factor
default_locale: Default locale
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: display_name, display_name_html, login_theme, account_theme, +21 more. Returns: result
Update an existing user.
Args:
user_id: The user's ID
username: New username
email: New email address
first_name: New first name
last_name: New last name
enabled: Whether the user is enabled
email_verified: Whether the email is verified
attributes: Updated user attributes
realm: Target realm (uses default if not specified)
Returns:
Status message
Inputs: user_id (required), username, email, first_name, +5 more. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 47 tools
Most tools have distinct purposes, but there is potential confusion between get_client and get_client_by_clientid (both retrieve a client) and between assign_client_role_to_user and assign_realm_role_to_user (both assign roles, just different scopes). Descriptions clarify, but the large number of tools may cause some ambiguity.
All tools follow a consistent snake_case verb_noun pattern (e.g., create_user, list_clients, update_realm_settings). Longer names like add_user_to_group are also consistent with verb_object_preposition_target style. No mixing of conventions.
47 tools is substantial but appropriate for a comprehensive Keycloak administration server covering realms, users, groups, clients, roles, and sessions. Each tool has a defined role, though a few could be merged without loss of clarity.
The tool surface is very broad, covering CRUD for all major entities plus password resets, session management, role assignments, and realm configuration. Notable gap: no tool to list a user's client roles (only realm roles). Otherwise, well-rounded.
Managed Keycloak from any MCP client: clusters, realms, apps, SSO, users, domains, audit events.
Keycloak identity management expert with semantic search, protocol guides, and config analysis
Users, organizations, roles, permissions, applications and feature flags.
Deploy and manage your apps on Qovery
