Keycloak MCP Server

An MCP server for Keycloak administration, offering over 30 tools to manage users, realms, clients, roles, and more from AI assistants.

A comprehensive Model Context Protocol (MCP) server for Keycloak administration, providing80+ toolsto manage users, realms, clients, roles, groups, sessions, events, organizations, protocol mappers, user attributes, client scopes, and identity providers directly from AI assistants like Claude Desktop or Cursor AI.

- ✅ Create, update, and delete users
- ✅ List, search, and get user details
- ✅ Reset user passwords
- ✅ Logout user sessions
- ✅ Manage user roles and groups
- ✅NEW:User attributes management (critical for organization data)

- ✅ List, create, update, and delete realms
- ✅ Get detailed realm settings and configurations
- ✅ Manage realm-level security policies

- ✅ Register, update, and delete clients/applications
- ✅ List all clients in realms
- ✅ Configure client settings and redirect URIs
- ✅NEW:Protocol mappers management (critical for JWT claims)

- ✅ Create, update, and delete roles (realm and client-level)
- ✅ Assign and remove roles from users and groups
- ✅ List all roles and user role assignments
- ✅NEW:Composite roles and role hierarchies
- ✅NEW:Advanced role operations by ID
- ✅NEW:Find users with specific roles

- ✅ Create, update, and delete user groups
- ✅ Add and remove users from groups
- ✅ Manage hierarchical group structures
- ✅NEW:Group attributes management
- ✅NEW:Child groups and subgroup management
- ✅NEW:Group member listing and management

- ✅ Create, update, and delete organizations
- ✅ Add and remove organization members
- ✅ List organizations and members
- ✅ Organization attributes management

- ✅ Create, update, and delete identity providers (SSO)
- ✅ Identity provider mapper management
- ✅ SAML and OIDC provider configuration
- ✅ External user attribute mapping

- ✅ Create, update, and delete client scopes
- ✅ Protocol mappers for client scopes
- ✅ Token scope management

- ✅ List active user sessions
- ✅ Monitor authentication and admin events
- ✅ Clear event logs and manage session lifecycles

- ✅Bulletproof authenticationwith fresh client instances
- ✅Comprehensive error handlingwith detailed logging
- ✅Cross-platform support(Windows, macOS, Linux)
- ✅Production-readywith TypeScript and robust architecture
- ✅Organization JWT Claims- Solve organization visibility in tokens
- ✅80+ Tools- Complete Keycloak administration coverage

- Node.js 18 or higher
- Running Keycloak instance(local or remote)
- Keycloak admin credentialswith appropriate permissions
- AI Assistantthat supports MCP (Claude Desktop, Cursor AI, etc.)

git clone https://github.com/M0-AR/keycloak-mcp-server.git cd keycloak-mcp-server npm install npm run build

Add to your Cursor MCP configuration file (~/.cursor/mcp.json):

{ "mcpServers": { "keycloak": { "command": "npx", "args": ["keycloak-mcp-server"], "env": { "KEYCLOAK_URL": "https://your-keycloak-instance.com", "KEYCLOAK_ADMIN": "your-admin-username", "KEYCLOAK_ADMIN_PASSWORD": "your-admin-password" } } } }

{ "mcpServers": { "keycloak": { "command": "keycloak-mcp-server", "env": { "KEYCLOAK_URL": "https://your-keycloak-instance.com", "KEYCLOAK_ADMIN": "your-admin-username", "KEYCLOAK_ADMIN_PASSWORD": "your-admin-password" } } } }

Add to your Claude Desktop configuration:

macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json

{ "mcpServers": { "keycloak": { "command": "npx", "args": ["keycloak-mcp-server"], "env": { "KEYCLOAK_URL": "https://your-keycloak-instance.com", "KEYCLOAK_ADMIN": "your-admin-username", "KEYCLOAK_ADMIN_PASSWORD": "your-admin-password" } } } }

Creates a new user in a specified realm.

Create a user in "master" realm: username "john.doe", email "john@example.com", first name "John", last name "Doe"

Updates user information (email, names, enabled status).

Update user "user-id-123" in "master" realm to change email to "newemail@example.com"

Delete user with ID "user-id-123" from "master" realm

List all users in the "master" realm

Search users with filters (username, email, firstName, lastName).

Search for users with email containing "wateen.io" in "master" realm, limit 10 results

Get detailed information about a specific user.

Get details for user ID "user-id-123" in "master" realm

Reset password for user "user-id-123" in "master" realm to "newPassword123", make it temporary

Logout all sessions for a specific user.

Logout all sessions for user "user-id-123" in "master" realm

Set user attributes (critical for organization data storage).

Set organization attribute for user "user-id-123" in "master" realm: {"organization": ["wateen-corp"]}

Get user attributes including unmanaged attributes.

Get all attributes for user "user-id-123" in "master" realm

Show me all available realms in Keycloak

Creates a new realm with configurable settings.

Create a new realm called "company" with display name "Company Realm", enabled

Updates realm settings and configurations.

Update realm "company" to change display name to "Updated Company"

Get detailed settings for the "master" realm

Registers a new client/application in a realm.

Create client "my-app" in "master" realm with redirect URIs ["http://localhost:3000/"]

Update client "my-app" in "master" realm to add new redirect URI "https://app.example.com/"

Delete client "old-app" from "master" realm

List all clients in the "master" realm

Create protocol mappers for clients (critical for JWT organization claims).

Create organization group mapper for client "my-app" in "master" realm to include "organization" claim in JWT

Update protocol mapper "mapper-id-123" for client "my-app" in "master" realm

Delete protocol mapper "mapper-id-123" from client "my-app" in "master" realm

List all protocol mappers for client "my-app" in "master" realm

Create a new client scope for managing token scopes.

Create client scope "organization-scope" in "master" realm for organization claims

Update client scope "scope-id-123" in "master" realm to change description

Delete client scope "scope-id-123" from "master" realm

List all client scopes in the "master" realm

Get details for client scope "scope-id-123" in "master" realm

create-client-scope-protocol-mapper⭐NEW

Create protocol mappers for client scopes.

Create organization mapper for client scope "organization-scope" in "master" realm

update-client-scope-protocol-mapper⭐NEW

Update protocol mappers in client scopes.

Update protocol mapper "mapper-id-123" in client scope "scope-id-456" in "master" realm

delete-client-scope-protocol-mapper⭐NEW

Delete protocol mappers from client scopes.

Delete protocol mapper "mapper-id-123" from client scope "scope-id-456" in "master" realm

list-client-scope-protocol-mappers⭐NEW

List protocol mappers for a client scope.

List all protocol mappers for client scope "scope-id-123" in "master" realm

Create organization "wateen-corp" with description "Wateen Corporation" in "master" realm

Update organization "org-id-123" in "master" realm to change name to "Updated Corp"

Delete organization "org-id-123" from "master" realm

List all organizations in "master" realm with search "wateen", limit 10

Get details for organization "org-id-123" in "master" realm

Add user "user-id-123" to organization "org-id-456" in "master" realm

Remove user "user-id-123" from organization "org-id-456" in "master" realm