Keycloak MCP Server

How to use

Connect your MCP client to the Keycloak MCP Server and start sending commands that cover user provisioning, client configuration, group and realm administration, and role-based access management. When you issue actions, you will be able to perform tasks such as creating users, assigning roles, configuring clients, and adjusting realm settings through natural language requests that map to the server’s available tools.

How to install

Prerequisites you need before installing:
- Python 3.8 or higher
- Access to a Keycloak server with admin credentials
- Optional: uvx or uv for local MCP runners, and npm for Smithery installation if you choose that path.

# Quick start: install the Python MCP package
pip install mcp-keycloak

# Run the server in standard stdio mode (default)
python -m src.main

# Run the server in HTTP mode on the default port
TRANSPORT=http python -m src.main

# Run HTTP mode on a custom port
TRANSPORT=http PORT=8080 python -m src.main

# Convenience script (if you have the script available)
./scripts/run_server.sh
```}]
}, {

Configuration

Configure connection to your Keycloak instance using environment variables. Provide the server URL, admin credentials, and the target realm. You can optionally specify OAuth2 client details if you plan to use client-side integrations.

# 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-secret
```}]} ,{

Security and deployment notes

The HTTP transport follows the MCP specification for secure, streamable communication. When deploying, consider these practices to protect your environment: use HTTPS with valid certificates and deploy behind a reverse proxy, apply strict firewall rules, and enable authentication at the network boundary if needed.

For local development, connections are designed to be simple and do not require user-level authentication by default. For production, add appropriate authentication and network protections.

Troubleshooting and tips

If you encounter connection issues, verify that your Keycloak server is reachable at SERVER_URL and that the REALM_NAME exists. Check that the MCP server is started with the correct mode (stdio for local CLI tools or http for network access) and ensure you are using the expected port and host. If you use the HTTP transport, confirm that you are sending requests to the /mcp/ endpoint and that the Accept header includes both application/json and text/event-stream when streaming responses.

Example usage scenarios

- Onboard a new user and assign realm roles to automate access provisioning for a new team.

Configure a new OAuth2 client for a service and grant it appropriate client roles.

list_users

List users with options for pagination and filtering.

create_user

Create a new user with optional attributes and credentials.

update_user

Update an existing user's attributes or credentials.

delete_user

Remove a user from the directory.

reset_user_password

Reset a user’s password.

get_user_sessions

Retrieve active sessions for a user.

logout_user

Log out a user from all sessions.

count_users

Return user statistics and counts.

list_clients

List OAuth2/OIDC clients in a realm.

get_client

Retrieve details for a specific client.

create_client

Create a new OAuth2/OIDC client.

get_client_secret

Fetch the client secret for a given client.

regenerate_client_secret

Regenerate the client secret.

get_client_service_account

Retrieve the service account associated with a client.

update_client

Update client configuration.

delete_client

Delete a client.

list_realm_roles

List roles defined at the realm level.

create_realm_role

Create a new realm-wide role.

list_client_roles

List roles defined for a specific client.

create_client_role

Create a new role for a client.

assign_realm_role_to_user

Assign a realm role to a user.

remove_realm_role_from_user

Remove a realm role from a user.

get_user_realm_roles

Get realm roles assigned to a user.

assign_client_role_to_user

Assign a client role to a user.

list_groups

List groups in a realm.

create_group

Create a new group.

update_group

Update a group's configuration.

get_group_members

Get members of a group.

add_user_to_group

Add a user to a group.

get_user_groups

List groups a user belongs to.

remove_user_from_group

Remove a user from a group.

get_accessible_realms

List realms accessible to the authenticated user.

get_realm_info

Retrieve realm information.

update_realm_settings

Update realm settings.

get_realm_events_config

Get realm events configuration.

update_realm_events_config

Update realm events configuration.

add_realm_default_group

Add a default group for a realm.

remove_realm_default_group

Remove a default group from a realm.

list_authentication_flows

List authentication flows.

get_authentication_flow

Get details of an authentication flow.

create_authentication_flow

Create a new authentication flow.

update_authentication_flow

Update an authentication flow.

delete_authentication_flow

Delete an authentication flow.

copy_authentication_flow

Copy an authentication flow.

get_flow_executions

Get executions within a flow.

update_flow_executions

Update executions for a flow.

create_execution

Create an authentication execution.

delete_execution

Delete an authentication execution.

get_authenticator_config

Get configuration for an authenticator.

create_authenticator_config

Create a new authenticator configuration.

get_required_actions

List required actions.

update_required_action

Update a required action configuration.