Content
# Keycloak MCP Server
[](https://img.shields.io/npm/v/keycloak-mcp)
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/keycloak-mcp)
[](https://www.npmjs.com/package/keycloak-mcp)
[](https://smithery.ai/server/@HaithamOumerzoug/keycloak-mcp)
A Model Context Protocol (MCP) server implementation for Keycloak, providing a standardized interface for managing Keycloak users and realms.
<a href="https://glama.ai/mcp/servers/@HaithamOumerzoug/keycloak-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@HaithamOumerzoug/keycloak-mcp/badge" alt="Keycloak Server MCP server" />
</a>
## 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](https://smithery.ai/server/@HaithamOumerzoug/keycloak-mcp):
```bash
$ 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:
```bash
# 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:
```json
{
"mcpServers": {
"keycloak": {
"command": "npx",
"args": ["-y", "keycloak-mcp"],
"env": {
"KEYCLOAK_URL": "http://localhost:8080",
"KEYCLOAK_ADMIN": "admin",
"KEYCLOAK_ADMIN_PASSWORD": "admin"
}
}
}
}
```
### For Local Development
```json
{
"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:
1. Clone the repository
2. Install dependencies:
```bash
npm install
```
3. Set env vars
```bash
cp .env.template .env
# Edit the .env file and set all variables with the appropriate values
```
4. Start the project:
```bash
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](https://www.linkedin.com/in/haitham-oumerzoug/)
