A Model Context Protocol (MCP) server that provides a natural language interface for managing Keycloak identity and access through REST API, enabling AI agents to perform user management, client configuration, realm administration, and role-based access control operations.

Installation

Smithery

npx -y @smithery/cli install mcp-keycloak --client claude

Pip

pip install mcp-keycloak

From Source Code

git clone https://github.com/idoyudha/mcp-keycloak.git
cd mcp-keycloak
pip install -e .

Configuration

uvx Setup

{
  "mcpServers": {
    "keycloak": {
      "command": "uvx",
      "args": ["mcp-keycloak"],
      "env": {
        "SERVER_URL": "https://your-keycloak.com",
        "USERNAME": "admin",
        "PASSWORD": "admin-password",
        "REALM_NAME": "your-realm"
      }
    }
  }
}

Local Development

{
  "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"
      }
    }
  }
}

Available Tools

Tool	Description
list_users	List users with pagination and filtering
create_user	Create a new user
update_user	Update an existing user
delete_user	Delete a user
reset_user_password	Reset a user's password
get_user_sessions	Get user sessions
logout_user	Log out a user from sessions
count_users	Get user statistics
list_clients	List OAuth2/OIDC clients
get_client	Get client details
create_client	Create a new client
get_client_secret	Get client secret
regenerate_client_secret	Regenerate client secret
get_client_service_account	Get client service account
update_client	Update client configuration

Features

• Comprehensive user management - Manage user lifecycle from creation to deletion, including password reset, session management, and user attribute updates
• Client configuration - Create and configure OAuth2/OIDC clients, manage client secrets, and programmatically handle service accounts
• Role-based access control - Define and assign realm and client roles, manage user permissions, and implement fine-grained access control
• Realm administration - Configure realm settings, manage default groups, handle event configurations, and control realm-level policies
• Authentication management - Comprehensive management of authentication flows, including flow creation, updates, deletion, execution management, and authenticator configuration
• Group management - Organize users into groups, manage group hierarchies, and efficiently handle group-based permissions
• HTTP transport support - Network accessibility with support for concurrent connections from multiple AI clients
• Streaming HTTP protocol - Follows MCP specification for HTTP transport with proper security implementations

Environment Variables

Required

• SERVER_URL - URL of your Keycloak server
• USERNAME - Admin username for Keycloak
• PASSWORD - Admin password for Keycloak
• REALM_NAME - Name of the target realm in Keycloak

Optional

• CLIENT_ID - Optional OAuth2 client ID
• CLIENT_SECRET - Optional OAuth2 client secret
• TRANSPORT - Transport mode (http for HTTP transport)
• PORT - Port for HTTP transport (default: 8000)

Usage Examples

AI-powered identity management - Create 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, ensuring automatic configuration of identity services

Notes

The server supports both stdio (default) and HTTP transports. HTTP transport offers network accessibility, multi-client support, and integration flexibility. Requires Python 3.8+ and Keycloak 18+ with admin rights to the target realm.