A comprehensive Model Context Protocol (MCP) server for Keycloak administration, providing 80+ tools to 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 authentication with fresh client instances
- ✅ Comprehensive error handling with detailed logging
- ✅ Cross-platform support (Windows, macOS, Linux)
- ✅ Production-ready with 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 credentials with appropriate permissions
- AI Assistant that supports MCP (Claude Desktop, Cursor AI, etc.)
npm install -g keycloak-mcp-servernpx keycloak-mcp-servernpm install keycloak-mcp-servergit clone https://github.com/M0-AR/keycloak-mcp-server.git
cd keycloak-mcp-server
npm install
npm run buildAdd 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.json
Windows: %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"
}
}
}
}| Variable | Description | Default | Required |
|---|---|---|---|
KEYCLOAK_URL |
The base URL of your Keycloak instance | http://localhost:8080 |
✅ |
KEYCLOAK_ADMIN |
Admin username | admin |
✅ |
KEYCLOAK_ADMIN_PASSWORD |
Admin password | admin |
✅ |
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"
Deletes a user from a realm.
Delete user with ID "user-id-123" from "master" realm
Lists all users in a 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 a user's password.
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
Lists all available realms.
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"
Deletes an existing realm.
Delete the realm "test-realm"
Retrieves detailed settings of a realm.
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/*"]
Updates client settings (redirect URIs, protocol mappers, etc.).
Update client "my-app" in "master" realm to add new redirect URI "https://app.example.com/*"
Removes a client from a realm.
Delete client "old-app" from "master" realm
Lists all clients in a 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 existing protocol mappers.
Update protocol mapper "mapper-id-123" for client "my-app" in "master" realm
Delete protocol mappers from clients.
Delete protocol mapper "mapper-id-123" from client "my-app" in "master" realm
List all protocol mappers for a client.
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 existing client scope.
Update client scope "scope-id-123" in "master" realm to change description
Delete a client scope.
Delete client scope "scope-id-123" from "master" realm
List all client scopes in a realm.
List all client scopes in the "master" realm
Get details of a specific client scope.
Get details for client scope "scope-id-123" in "master" realm
Create protocol mappers for client scopes.
Create organization mapper for client scope "organization-scope" in "master" realm
Update protocol mappers in client scopes.
Update protocol mapper "mapper-id-123" in client scope "scope-id-456" in "master" realm
Delete protocol mappers from client scopes.
Delete protocol mapper "mapper-id-123" from client scope "scope-id-456" in "master" realm
List protocol mappers for a client scope.
List all protocol mappers for client scope "scope-id-123" in "master" realm
Create a new organization.
Create organization "wateen-corp" with description "Wateen Corporation" in "master" realm
Update existing organization.
Update organization "org-id-123" in "master" realm to change name to "Updated Corp"
Delete an organization.
Delete organization "org-id-123" from "master" realm
List all organizations in a realm.
List all organizations in "master" realm with search "wateen", limit 10
Get details of a specific organization.
Get details for organization "org-id-123" in "master" realm
Add a user to an organization.
Add user "user-id-123" to organization "org-id-456" in "master" realm
Remove a user from an organization.
Remove user "user-id-123" from organization "org-id-456" in "master" realm
List all members of an organization.
List all members of organization "org-id-123" in "master" realm, limit 20
Creates roles at realm or client level.
Create a realm role "manager" with description "Manager role" in "master" realm
Modifies role attributes.
Update role "manager" in "master" realm to change description to "Updated manager role"
Deletes roles.
Delete role "old-role" from "master" realm
Lists all roles in a realm.
List all roles in the "master" realm
Assigns a role to a user.
Assign role "manager" to user "user-id-123" in "master" realm
Removes a role from a user.
Remove role "manager" from user "user-id-123" in "master" realm
Gets all roles assigned to a user.
Get all roles for user "user-id-123" in "master" realm
Create composite roles (role hierarchies).
Create composite role from "parent-role-id" with child roles ["child-role-1", "child-role-2"] in "master" realm
Get composite roles for a role.
Get composite roles for role "role-id-123" in "master" realm, limit 10
Delete composite roles from a role.
Remove composite roles ["child-role-1", "child-role-2"] from role "parent-role-id" in "master" realm
Get role details by ID.
Get role details for role ID "role-id-123" in "master" realm
Update role by ID.
Update role "role-id-123" in "master" realm to change name to "new-role-name"
Delete role by ID.
Delete role with ID "role-id-123" from "master" realm
Find users with a specific role.
Find all users with role "manager" in "master" realm, limit 20
Assign a role to a group.
Assign role "developer" to group "group-id-123" in "master" realm
Remove a role from a group.
Remove role "developer" from group "group-id-123" in "master" realm
Get roles assigned to a group.
Get all roles for group "group-id-123" in "master" realm
List available roles for a group.
List available roles for group "group-id-123" in "master" realm
List composite roles for a group.
List composite roles for group "group-id-123" in "master" realm
Creates user groups.
Create a group called "developers" in "master" realm
Updates group attributes.
Update group "group-id-123" in "master" realm to change name to "senior-developers"
Deletes groups.
Delete group "group-id-123" from "master" realm
Lists all groups in a realm.
List all groups in the "master" realm
Adds or removes users from groups.
Add user "user-id-123" to group "group-id-456" in "master" realm
Set group attributes (organization metadata).
Set organization attributes for group "group-id-123" in "master" realm: {"department": ["engineering"]}
Get group attributes.
Get all attributes for group "group-id-123" in "master" realm
Create a child group (subgroup).
Create child group "junior-devs" under parent group "group-id-123" in "master" realm
List subgroups of a parent group.
List subgroups of parent group "group-id-123" in "master" realm, limit 10
List members of a group.
List all members of group "group-id-123" in "master" realm, limit 20
Create a new identity provider for SSO integration.
Create SAML identity provider "company-saml" in "master" realm with SSO URL and certificate
Update an existing identity provider.
Update identity provider "company-saml" in "master" realm to change display name
Delete an identity provider.
Delete identity provider "old-saml" from "master" realm
List all identity providers in a realm.
List all identity providers in "master" realm
Get details of a specific identity provider.
Get details for identity provider "company-saml" in "master" realm
Create a mapper for identity provider (external user mapping).
Create user attribute mapper for identity provider "company-saml" in "master" realm
Update an identity provider mapper.
Update mapper "mapper-id-123" for identity provider "company-saml" in "master" realm
Lists all active sessions in a realm.
List all active sessions in "master" realm
Lists active sessions for a specific user.
Get active sessions for user "user-id-123" in "master" realm
Retrieves authentication and admin events.
List last 10 events in "master" realm
Clears event logs.
Clear all events in "master" realm
npx @modelcontextprotocol/inspector npx keycloak-mcp-serverVisit http://localhost:6274 to test all 80+ tools interactively.
npm run watch # Auto-rebuild on changes
npm run dev # Test server directlyThe server has been stress-tested with 80+ consecutive operations without authentication failures, demonstrating production-level reliability.
- Fresh Client Instances: Creates new KcAdminClient for every request
- Retry Logic: Exponential backoff with 2 attempts maximum
- Connection Management: 15-second timeout with proper cleanup
- Error Handling: Comprehensive error messages for all scenarios
- Type Safety: Full TypeScript coverage with proper interfaces
- Error Handling: Detailed error messages and logging
- Modular Design: Clean separation of concerns
This package has been extensively tested and validated:
- ✅ 80+ consecutive operations without authentication failures
- ✅ Cross-realm operations working seamlessly
- ✅ Parallel tool execution supported
- ✅ Complex search queries with multiple filters
- ✅ Error recovery and detailed logging
- ✅ TypeScript compilation with zero errors
- ✅ Complete Keycloak API coverage with organization management
This package specifically addresses the common JWT organization problem:
- ✅ User Attributes: Store organization data in user attributes
- ✅ Protocol Mappers: Create mappers to include organization in JWT tokens
- ✅ Client Scopes: Manage token scopes for organization claims
- ✅ Organizations: Full organization lifecycle management
- ✅ Group Attributes: Store organization metadata in groups
Example workflow:
- Create organization using
create-organization - Set user organization attribute using
set-user-attributes - Create protocol mapper using
create-protocol-mapperto include organization in JWT - Add user to organization using
add-organization-member
- Use environment variables for credentials
- Enable HTTPS for production Keycloak instances
- Use strong admin passwords
- Regularly rotate credentials
- Monitor admin events and sessions
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Open a Pull Request
MIT License - see LICENSE file for details.
- GitHub Issues: Create an issue
- Documentation: Check this README for comprehensive examples
- MCP Documentation: Model Context Protocol
- Claude Desktop - AI assistant supporting MCP
- Cursor AI - AI-powered code editor with MCP support
- Model Context Protocol - Protocol specification
- Keycloak - Open source identity and access management
- 80+ Tools: Complete Keycloak administration coverage
- Production Ready: Extensively tested and validated
- TypeScript: Full type safety and modern development experience
- Cross-Platform: Windows, macOS, and Linux support
- Zero Dependencies Issues: Robust dependency management
- Organization Management: Solve JWT organization visibility problems
- Advanced Features: Protocol mappers, client scopes, identity providers
Made with ❤️ for the Keycloak and AI community