Keycloak MCP

🚀 Keycloak MCP

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

🚀 Quick Start

Keycloak MCP is an MCP server integrated with Keycloak, enabling you to manage Keycloak users and realms through a standardized protocol. It interacts with Keycloak's API using the official Keycloak Admin Client.

✨ Features

• Feature Demo: Check out the demo here.
• 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

📦 Installation

Prerequisites

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

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

The server is available as an NPM package:

# Direct usage with npx
npx -y keycloak-mcp

# Or global installation
npm install -g keycloak-mcp

📚 Documentation

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/index.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:

   npm install
   

3. Build the project:

   npm run build
   

4. Start the project:

   npm run watch
   

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 watch - Watches for changes and rebuilds automatically

Dependencies

Main Dependencies

• @keycloak/keycloak-admin-client - Official Keycloak Admin Client
• @modelcontextprotocol/sdk - MCP SDK for standardized protocol implementation
• zod - TypeScript-first schema validation

Dev Dependencies

• typescript - For TypeScript support
• @types/node - TypeScript definitions for Node.js
• shx - Cross-platform shell commands

📄 License

This project is licensed under the MIT license.

👨‍💻 Author

OUMERZOUG Haitham