auth-security

Keycloak▌

by haithamoumerzoug

Integrate with Keycloak for user creation, role assignment, group, and client management across realms using Keycloak id

Integrates with Keycloak identity management to enable user creation, role assignment, group management, and client listing across different realms

github stars

★ 10

GitHub npm

Uses official Keycloak Admin ClientMulti-realm support

best for

/ Identity administrators managing user accounts
/ DevOps teams automating user provisioning
/ Applications needing Keycloak integration

capabilities

/ Create and delete users in Keycloak realms
/ List all users within specific realms
/ Browse available realms and clients
/ Manage groups across different realms
/ Query realm configurations and settings

what it does

Connects to Keycloak identity management systems to manage users, realms, groups, and clients through a standardized interface.

about

Keycloak is a community-built MCP server published by haithamoumerzoug that provides AI assistants with tools and capabilities via the Model Context Protocol. Integrate with Keycloak for user creation, role assignment, group, and client management across realms using Keycloak id It is categorized under auth security.

how to install

You can install Keycloak in your AI client of choice. Use the install panel on this page to get one-click setup for Cursor, Claude Desktop, VS Code, and other MCP-compatible clients. This server runs locally on your machine via the stdio transport.

license

MIT

Keycloak is released under the MIT license. This is a permissive open-source license, meaning you can freely use, modify, and distribute the software.

readme

Keycloak MCP Server

A Model Context Protocol (MCP) server implementation for Keycloak, providing a standardized interface for managing Keycloak users and realms.

Description

This project implements an MCP server that integrates with Keycloak, allowing you to manage Keycloak users and realms through a standardized protocol. It uses the official Keycloak Admin Client to interact with Keycloak's API.

Feature Demo

https://github.com/user-attachments/assets/4b02a049-b8d6-4cc5-a7b4-564a0e758dd8

Available Tools

create-user

Creates a new user in a specified realm.

Inputs:

realm: The realm name
username: Username for the new user
email: Email address for the user
firstName: User's first name
lastName: User's last name

delete-user

Deletes a user from a specified realm.

Inputs:

realm: The realm name
userId: The ID of the user to delete

list-realms

Lists all available realms.

list-users

Lists all users in a specified realm.

Inputs:

realm: The realm name

list-clients

Lists all clients in a specified realm.

Inputs:

realm: The realm name

list-groups

Lists all groups in a specified realm.

Inputs:

realm: The realm name

list-client-roles

Lists all roles for a specific client in a realm.

Inputs:

realm: The realm name
clientUniqueId: The unique ID of the client

assign-client-role-to-user

Assigns a client role to a specific user.

Inputs:

realm: The realm name
userId: The ID of the user
clientUniqueId: The unique ID of the client
roleName: The name of the role to assign

add-user-to-group

Adds a user to a specific group.

Inputs:

realm: The realm name
userId: The ID of the user
groupId: The ID of the group

Prerequisites

Node.js (Latest LTS version recommended)
npm
A running Keycloak instance

Installation

Installing via Smithery

To install keycloak-mcp for Claude Desktop automatically via Smithery:

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

Installing via NPM

Configure environment:

You can set configuration options using command-line arguments or environment variables:
- --keycloak-url <Keycloak Instance URL>
- --keycloak-admin <Admin Username>
- --keycloak-admin-password <Admin Password>
These arguments override environment variables if both are set.

Start the server:

The server is available as an NPM package:

# Direct usage with npx
$ npx -y keycloak-mcp --keycloak-url <Keycloak Instance URL> --keycloak-admin <Admin Username> --keycloak-admin-password <Admin Password>

# Or global installation
$ npm install -g keycloak-mcp@latest
$ keycloak-mcp --keycloak-url <Keycloak Instance URL> --keycloak-admin <Admin Username> --keycloak-admin-password <Admin Password>

Configuration

Using NPM Package

Configure the server in your Cursor IDE, Cline or Claude Desktop MCP configuration file:

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": ["-y", "keycloak-mcp"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

For Local Development

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": ["path/to/dist/server.js"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

Development

To set up the development environment:

Clone the repository
Install dependencies:
```
npm install
```

Set env vars

cp .env.template .env
# Edit the .env file and set all variables with the appropriate values

Start the project:
```
npm run dev
```

Available Scripts

npm run build - Builds the project and makes the CLI executable
npm run prepare - Runs the build script (used during package installation)
npm run dev - Watches for changes and rebuilds automatically
npm start - Starts the server (for production)

Dependencies

Main Dependencies

@keycloak/keycloak-admin-client - Official Keycloak Admin Client
@modelcontextprotocol/sdk - MCP SDK for standardized protocol implementation
zod - TypeScript-first schema validation
chalk - Terminal string styling
yargs - Parsing command-line arguments

Dev Dependencies

typescript - For TypeScript support
@types/node - TypeScript definitions for Node.js
shx - Cross-platform shell commands
ts-node - TypeScript execution and REPL for Node.js
rimraf - A cross-platform tool to remove directories
@types/yargs - TypeScript definitions for yargs

License

MIT

Author

OUMERZOUG Haitham