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:

bashCopy code
$ 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:

bashCopy code
# 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:

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

For Local Development

jsonCopy code
{
  "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:

   bashCopy code
   npm install
   

3. Set env vars

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

4. Start the project:

   bashCopy code
   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