Keycloak Model Context Protocol Server

Note: This project is a fork of M0-AR/keycloak-mcp-server explicitly modified to secure the server using Keycloak as the Identity Provider (IdP). It implements the official MCP Authorization architecture: CIMD (Client ID Metadata Document) is the preferred path, with DCR (Dynamic Client Registration) explicitly configured as a legacy fallback.

✅ Validated with: Built-in VS Code MCP Client and Claude Code CLI.

📖 Sources & Specifications:

Keycloak MCP Authorization Server Documentation

MCP Authorization Specification (2026-07-28)

A powerful Model Context Protocol (MCP) server that allows AI models to manage Keycloak realms, users, clients, and groups securely using Keycloak's own authentication mechanisms. It provides 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 Code CLI or VS Code.

🚀 Features

👤 User Management

✅ Create, update, and delete users (including email verified status)
✅ 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)

🏛️ Realm Management

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

🔧 Client Management

✅ 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)

🎭 Role Management

✅ 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

👥 Group Management

✅ 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

🏢 Organization Management ⭐ NEW

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

🔗 Identity Provider Management ⭐ NEW

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

🎯 Client Scopes Management ⭐ NEW

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

📊 Session & Event Management

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

🛡️ Advanced Features

✅ 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

📋 Prerequisites

Node.js 18 or higher
Running Keycloak instance (local or remote)
Keycloak admin credentials (Service Account) with appropriate permissions
VS Code or Claude Code CLI

💻 Local Development

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

📄 Using `.env` File (Required)

You must create a .env file in the root directory to configure the server (see Environment Variables below).

After configuring your .env, start the server:

npm start

🌍 Environment Variables

Variable	Description	Default	Required
`KEYCLOAK_URL`	The base URL of your Keycloak instance	`http://localhost:8080`	✅
`KEYCLOAK_ADMIN`	Admin username (Service Account) for backend API calls	`""`	❌ (Required if `KEYCLOAK_AUTH_MODE=service-account`)
`KEYCLOAK_ADMIN_PASSWORD`	Admin password (Service Account) for backend API calls	`""`	❌ (Required if `KEYCLOAK_AUTH_MODE=service-account`)
`KEYCLOAK_REALM`	The Keycloak realm to authenticate the admin client against	`master`	❌
`KEYCLOAK_AUTH_MODE`	Backend auth mode (`service-account` or `delegated-token`)	`service-account`	❌
`PORT`	The port for the Streamable HTTP / SSE server	`3000`	❌
`HOST`	The host for the Streamable HTTP / SSE server	`localhost`	❌
`MCP_TRANSPORT`	Set to `sse` to start the HTTP/Streamable server instead of `stdio`	`undefined`	❌
`OAUTH_ISSUER_URL`	Keycloak realm URL (e.g., `http://localhost:8080/realms/master`)	`undefined`	✅
`OAUTH_CLIENT_ID`	Client ID in Keycloak used by the MCP Server to introspect tokens	`undefined`	✅
`OAUTH_CLIENT_SECRET`	Client Secret for the `OAUTH_CLIENT_ID` to perform introspection	`""`	✅
`OAUTH_SCOPES`	Comma-separated list of OAuth scopes required for the server	`undefined`	✅
`OAUTH_AUDIENCE`	Additional expected `aud` claim in the client's access token	`undefined`	❌
`MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL`	Bypasses HTTPS requirements for `OAUTH_ISSUER_URL` in development	`false`	❌
`MCP_DEBUG`	Set to `true` to print raw access tokens to the console for debugging	`false`	❌

🛡️ OAuth 2.1 Resource Server (Streamable HTTP / SSE)

This MCP server strictly implements the official Model Context Protocol Authorization Specification (OAuth 2.1) to secure tools and resources. Rather than relying on simple offline JWT verification, this server uses Online Token Introspection (RFC 7662) via Keycloak. This means if an administrator kills a user's session in Keycloak, their MCP access is revoked instantly!

The server supports the modern Streamable HTTP transport on the root / endpoint, as well as legacy SSE on /sse and /message.

🔄 Architecture & Authentication Flow

This server implements the official MCP Authorization flow decision tree:

CIMD (Default/Preferred): If both the client and server support it, they will use Client ID Metadata Documents (e.g. client_id=https://claude.ai/...).
DCR (Fallback): If CIMD is not supported, the server explicitly advertises its registration_endpoint, allowing the client to fall back to Dynamic Client Registration to get a random client_id assigned by Keycloak. Note: You must configure your Keycloak realm to allow dynamic client registration (e.g. via Initial Access Tokens or anonymous DCR policies) for this fallback to work.

Below is the complete sequence of how an MCP Client (like VS Code or Claude Code) securely authenticates with Keycloak via the preferred CIMD path:

sequenceDiagram
    participant C as MCP Client (VS Code / Claude Code)
    participant S as MCP Server
    participant K as Keycloak
    participant M as CIMD Endpoint

    %% Initial Connection & Discovery
    C->>S: 1. Connect (No Token)
    S-->>C: 2. 401 Unauthorized + WWW-Authenticate header
    note over C,S: PRM Discovery
    C->>S: 3. Fetch /.well-known/oauth-protected-resource
    S-->>C: 4. Returns PRM Document (Issuer URL)

    note over C,K: Authentication using CIMD (No DCR!)
    C->>K: 5. Auth Request: client_id=https://host/client-metadata.json
    K->>M: 6. Fetch https://host/client-metadata.json
    M-->>K: 7. Returns Client Metadata Document JSON
    
    Note over K: Validates client_id & PKCE (No secret needed)
    C->>K: 8. Open browser for User Login
    K-->>C: 9. Issues access_token & refresh_token

    %% Authenticated MCP Request
    C->>S: 10. Connect (Bearer access_token)
    Note over S,K: Online Token Introspection (RFC 7662)
    S->>K: 11. POST /token/introspect (Using pre-configured client secret)
    K-->>S: 12. Token valid? (Checks expiry & audience)
    S-->>C: 13. Accept Connection & Execute Tools

🔒 Connecting MCP Clients (CIMD)

Because this server strictly enforces CIMD, your client must support connecting via the metadata document flow.

VS Code

VS Code uses CIMD by default (client_id=https://vscode.dev/oauth/client-metadata.json), so you can connect directly:

{
  "mcpServers": {
    "keycloak-mcp-server": {
      "type": "http",
      "url": "http://localhost:3000"
    }
  }
}

Claude Code

You can add the Keycloak MCP Server to Claude Code directly from the CLI using the http transport:

claude mcp add --transport http keycloak-mcp-server http://localhost:3000

🔧 Step 1: Start Keycloak with CIMD Feature

Keycloak supports CIMD starting in version 26.6.0. You must start Keycloak with the feature flag enabled:

bin/kc.[sh|bat] start --features=cimd

🛡️ Step 2: Configure Client Policies (For Claude Code & VS Code)

Because both Claude Code and VS Code desktop clients use localhost (or 127.0.0.1) for OAuth redirects rather than their primary metadata domains, they violate Keycloak's default "Restrict same domain" security rule. You must explicitly configure Keycloak Client Profiles and Policies to allow them.

For Claude Code Desktop

Go to Realm Settings -> Client Policies -> Profiles tab. Create a new Profile named claude-code-cimd-profile.
Add the client-id-metadata-document executor to the profile and configure it:
- Trusted domains: claude.ai, localhost, 127.0.0.1
- Restrict same domain: OFF
- Only Allow Confidential Client: OFF
Go to the Policies tab and create a new Policy named claude-code-cimd-policy.
Add a Condition of type client-id-uri and configure it:
- URI scheme: https
- Trusted domains: claude.ai
Under Associated client profiles, link this policy to your claude-code-cimd-profile.

For Visual Studio Code Desktop

Go to Realm Settings -> Client Policies -> Profiles tab. Create a new Profile named vscode-cimd-profile.
Add the client-id-metadata-document executor to the profile and configure it:
- Allow http scheme: OFF
- Trusted domains: vscode.dev, 127.0.0.1, code.visualstudio.com
- Restrict same domain: OFF
- Only Allow Confidential Client: OFF
Go to the Policies tab and create a new Policy named vscode-cimd-policy.
Add a Condition of type client-id-uri and configure it:
- URI scheme: https
- Trusted domains: vscode.dev
Under Associated client profiles, link this policy to your vscode-cimd-profile.

🔑 Step 3: Configure Token Introspection Client

To securely validate the access tokens, the MCP server needs its own dedicated client in Keycloak:

In the Keycloak Admin Console, go to Clients -> Create client.
Client ID: Set this to your desired client ID, and explicitly export it as the OAUTH_CLIENT_ID environment variable.
Ensure Client authentication is turned ON (required for token introspection).
Click Save, navigate to the Credentials tab, and copy the Client Secret to your .env file.

🎯 Step 4: Configure Client Scopes & Audiences

Because Keycloak strictly enforces token audiences during introspection, the tokens issued to your AI clients (like Claude Code CLI) must include the proper audiences:

In Keycloak, create a new Client Scope named mcp-admin (Type: Optional).
Go to the Scope tab, disable Full Scope Allowed, and assign the specific realm-management roles you want the AI to have access to.
Go to the Mappers tab and click Configure a new mapper -> Audience.
Name it mcp-server-audience and set the Included Client Audience to mcp-server. (This allows the MCP server to inspect the token).
Add another Audience Mapper named mcp-url-audience and set the Included Custom Audience to your server URL (e.g., http://localhost:3000). (This allows the MCP SDK to accept the token).

🚀 Step 5: Start the Protected MCP Server

Provide the necessary environment variables to start the server in protected mode:

export OAUTH_ISSUER_URL="http://localhost:8080/realms/master"
export OAUTH_CLIENT_ID="mcp-server"
export OAUTH_CLIENT_SECRET="your-copied-client-secret"

# If developing locally without HTTPS, the start/dev scripts automatically handle this:
npm run dev

When an MCP Client connects to http://localhost:3000, it will automatically receive a 401 Unauthorized with a WWW-Authenticate header pointing to /.well-known/oauth-protected-resource. The client will perform the OAuth flow and seamlessly reconnect with a valid access token!

🛠️ Available Tools (85+ Tools)

👤 User Management Tools

`create-user`

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"

`update-user`

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

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

`delete-user`

Deletes a user from a realm.

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

`list-users`

Lists all users in a realm.

List all users in the "master" realm

`search-users`

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

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

`get-user`

Get detailed information about a specific user.

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

`reset-user-password`

Reset a user's password.

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

`logout-user`

Logout all sessions for a specific user.

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

`set-user-attributes` ⭐ NEW

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` ⭐ NEW

Get user attributes including unmanaged attributes.

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

🏛️ Realm Management Tools

`list-realms`

Lists all available realms.

Show me all available realms in Keycloak

`create-realm`

Creates a new realm with configurable settings.

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

`update-realm`

Updates realm settings and configurations.

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

`delete-realm`

Deletes an existing realm.

Delete the realm "test-realm"

`get-realm-settings`

Retrieves detailed settings of a realm.

Get detailed settings for the "master" realm

🔧 Client Management Tools

`create-client`

Registers a new client/application in a realm.

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

`update-client`

Updates client settings (redirect URIs, protocol mappers, etc.).

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

`delete-client`

Removes a client from a realm.

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

`list-clients`

Lists all clients in a realm.

List all clients in the "master" realm

`create-protocol-mapper` ⭐ NEW

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` ⭐ NEW

Update existing protocol mappers.

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

`delete-protocol-mapper` ⭐ NEW

Delete protocol mappers from clients.

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

`list-protocol-mappers` ⭐ NEW

List all protocol mappers for a client.

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

🎯 Client Scopes Management Tools ⭐ NEW

`create-client-scope`

Create a new client scope for managing token scopes.

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

`update-client-scope`

Update existing client scope.

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

`delete-client-scope`

Delete a client scope.

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

`list-client-scopes`

List all client scopes in a realm.

List all client scopes in the "master" realm

`get-client-scope`

Get details of a specific client scope.

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

🏢 Organization Management Tools ⭐ NEW

`create-organization`

Create a new organization.

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

`update-organization`

Update existing organization.

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

`delete-organization`

Delete an organization.

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

`list-organizations`

List all organizations in a realm.

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

`get-organization`

Get details of a specific organization.

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

`add-organization-member`

Add a user to an organization.

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

`remove-organization-member`

Remove a user from an organization.

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

`list-organization-members`

List all members of an organization.

List all members of organization "org-id-123" in "master" realm, limit 20

🎭 Role Management Tools

`create-role`

Creates roles at realm or client level.

Create a realm role "manager" with description "Manager role" in "master" realm

`update-role`

Modifies role attributes.

Update role "manager" in "master" realm to change description to "Updated manager role"

`delete-role`

Deletes roles.

Delete role "old-role" from "master" realm

`list-roles`

Lists all roles in a realm.

List all roles in the "master" realm

`assign-role-to-user`

Assigns a role to a user.

Assign role "manager" to user "user-id-123" in "master" realm

`remove-role-from-user`

Removes a role from a user.

Remove role "manager" from user "user-id-123" in "master" realm

`get-user-roles`

Gets all roles assigned to a user.

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

`create-composite-role` ⭐ NEW

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` ⭐ NEW

Get composite roles for a role.

Get composite roles for role "role-id-123" in "master" realm, limit 10

`delete-composite-roles` ⭐ NEW

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-by-id` ⭐ NEW

Get role details by ID.

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

`update-role-by-id` ⭐ NEW

Update role by ID.

Update role "role-id-123" in "master" realm to change name to "new-role-name"

`delete-role-by-id` ⭐ NEW

Delete role by ID.

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

`find-users-with-role` ⭐ NEW

Find users with a specific role.

Find all users with role "manager" in "master" realm, limit 20

`assign-role-to-group` ⭐ NEW

Assign a role to a group.

Assign role "developer" to group "group-id-123" in "master" realm

`remove-role-from-group` ⭐ NEW

Remove a role from a group.

Remove role "developer" from group "group-id-123" in "master" realm

`get-group-roles` ⭐ NEW

Get roles assigned to a group.

Get all roles for group "group-id-123" in "master" realm

`list-available-group-roles` ⭐ NEW

List available roles for a group.

List available roles for group "group-id-123" in "master" realm

`list-composite-group-roles` ⭐ NEW

List composite roles for a group.

List composite roles for group "group-id-123" in "master" realm

👥 Group Management Tools

`create-group`

Creates user groups.

Create a group called "developers" in "master" realm

`update-group`

Updates group attributes.

Update group "group-id-123" in "master" realm to change name to "senior-developers"

`delete-group`

Deletes groups.

Delete group "group-id-123" from "master" realm

`list-groups`

Lists all groups in a realm.

List all groups in the "master" realm

`manage-user-groups`

Adds or removes users from groups.

Add user "user-id-123" to group "group-id-456" in "master" realm

`set-group-attributes` ⭐ NEW

Set group attributes (organization metadata).

Set organization attributes for group "group-id-123" in "master" realm: {"department": ["engineering"]}

`get-group-attributes` ⭐ NEW

Get group attributes.

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

`create-child-group` ⭐ NEW

Create a child group (subgroup).

Create child group "junior-devs" under parent group "group-id-123" in "master" realm

`list-sub-groups` ⭐ NEW

List subgroups of a parent group.

List subgroups of parent group "group-id-123" in "master" realm, limit 10

`list-group-members` ⭐ NEW

List members of a group.

List all members of group "group-id-123" in "master" realm, limit 20

🔗 Identity Provider Management Tools ⭐ NEW

`create-identity-provider`

Create a new identity provider for SSO integration.

Create SAML identity provider "company-saml" in "master" realm with SSO URL and certificate

`update-identity-provider`

Update an existing identity provider.

Update identity provider "company-saml" in "master" realm to change display name

`delete-identity-provider`

Delete an identity provider.

Delete identity provider "old-saml" from "master" realm

`list-identity-providers`

List all identity providers in a realm.

List all identity providers in "master" realm

`get-identity-provider`

Get details of a specific identity provider.

Get details for identity provider "company-saml" in "master" realm

`create-identity-provider-mapper`

Create a mapper for identity provider (external user mapping).

Create user attribute mapper for identity provider "company-saml" in "master" realm

`update-identity-provider-mapper`

Update an identity provider mapper.

Update mapper "mapper-id-123" for identity provider "company-saml" in "master" realm

`delete-identity-provider-mapper`

Delete an identity provider mapper.

Delete identity provider mapper "mapperId" for "alias" in "realm" realm

`get-identity-provider-mapper`

Get an identity provider mapper by ID.

Get identity provider mapper "mapperId" for "alias" in "realm" realm

`import-identity-provider-from-url`

Import an identity provider from a URL.

Import identity provider from URL "providerUrl" with ID "providerId" in "realm" realm

`list-identity-provider-mapper-types`

List available identity provider mapper types.

List available identity provider mapper types for "alias" in "realm" realm

`list-identity-provider-mappers`

List all mappers for an identity provider.

List all mappers for identity provider "alias" in "realm" realm

📊 Session & Event Management Tools

`list-sessions`

Lists all active sessions in a realm.

List all active sessions in "master" realm

`get-user-sessions`

Lists active sessions for a specific user.

Get active sessions for user "user-id-123" in "master" realm

`list-events`

Retrieves authentication and admin events.

List last 10 events in "master" realm

`clear-events`

Clears event logs.

Clear all events in "master" realm

🔧 Troubleshooting

Keycloak Crash: `Condition with provider ID client-id-uri not found`

If you decide to deactivate CIMD on Keycloak (by removing --features=cimd), but you later see this java.lang.IllegalStateException in Keycloak logs during client registration: This happens because you still have the CIMD Client Policy active in your Keycloak database, but you removed the underlying Java code feature (client-id-uri) that the policy relies on. To fix:

Re-enable the --features=cimd flag temporarily and restart Keycloak so it stops crashing.
Go to Realm Settings > Client Policies > Policies and Delete the CIMD policy you created.
Remove the --features=cimd flag and restart Keycloak. DCR will now work normally.

403 Forbidden in `delegated-token` mode

If you enable KEYCLOAK_AUTH_MODE=delegated-token and get a 403 Permission Denied error when the MCP client tries to run a tool, even though the user has admin roles, this is because of Keycloak's strict Audience validation. When you log in manually using client_id=admin-cli, Keycloak automatically adds the realm-management audience to your token. However, when an MCP client like Claude Code logs in using Dynamic Client Registration (DCR), Keycloak does not add the realm-management audience to its token by default, causing the Keycloak Admin API to reject it.

To fix this in Keycloak:

Open the Keycloak Admin Console and go to your realm.
Go to Client Scopes -> Create client scope (if it doesn't already exist). Name it mcp-admin, set Type to Default, and save. (The MCP server automatically requests this scope during OAuth).
Go to the Mappers tab of the mcp-admin scope -> Configure a new mapper -> Audience. Name it realm-management-aud, set Included Client Audience to realm-management, make sure Add to access token is ON, and save.
CRITICAL STEP (Role Scoping): Go to the Scope tab of the mcp-admin scope. Turn OFF "Full Scope Allowed" if it is on. Click Assign role, filter by clients, find the realm-management client, and assign the roles the MCP needs (e.g., view-users, manage-users, query-users, manage-clients).
Run a command to force Claude Code to fetch a fresh token (or run claude logout and reconnect).

Why step 4 is required: Dynamically registered clients have "Full Scope Allowed" turned OFF by default for security. Even if you map the audience, Keycloak will actively strip your admin roles from the token because the DCR client isn't "allowed" to ask for them! Adding them to the Scope tab explicitly whitelists those roles for any client requesting the mcp-admin scope.

🧪 Testing & Development

Testing with MCP Inspector

npx @modelcontextprotocol/inspector npx keycloak-mcp-server

Visit http://localhost:6274 to test all 80+ tools interactively.

Local Development

npm run watch    # Auto-rebuild on changes
npm run dev     # Test server directly

Stress Testing

The server has been stress-tested with 80+ consecutive operations without authentication failures, demonstrating production-level reliability.

🔧 Architecture

Bulletproof Authentication System

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

TypeScript Implementation

Type Safety: Full TypeScript coverage with proper interfaces
Error Handling: Detailed error messages and logging
Modular Design: Clean separation of concerns

📈 Production Ready

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

🎯 JWT Organization Problem Solved

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-mapper to include organization in JWT
Add user to organization using add-organization-member

🔒 Security Best Practices

Use environment variables for credentials
Enable HTTPS for production Keycloak instances
Use strong admin passwords
Regularly rotate credentials
Monitor admin events and sessions

🤝 Contributing

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

📄 License

MIT License - see LICENSE file for details.

🆘 Support

GitHub Issues: Create an issue
Documentation: Check this README for comprehensive examples
MCP Documentation: Model Context Protocol

🔗 Related Projects

Claude Desktop - AI assistant supporting MCP
VS Code - Code editor with MCP support
Model Context Protocol - Protocol specification
Keycloak - Open source identity and access management

📊 Package Stats

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

Name		Name	Last commit message	Last commit date
src		src
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
mcp.example.json		mcp.example.json
package-lock.json		package-lock.json
package.json		package.json
setup.sh		setup.sh
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation