Keycloak Admin

🚀 Keycloak MCP Server

A server for managing the Model Context Protocol (MCP) in Keycloak, providing tools to manage users and realms.

🚀 Quick Start

The Keycloak MCP Server is designed to manage the Model Context Protocol in Keycloak. It offers a set of tools to handle user and realm management tasks efficiently.

✨ Features

• Create new users in a specific realm.
• Delete users from a realm.
• List available realms.
• List users in a specific realm.

📦 Installation

Install via Smithery

To automatically install Keycloak via Smithery:

npx -y @smithery/cli install keycloak-model-context-protocol --client claude

Install via NPM (Recommended)

The server is available as an NPM package:

# Run directly using npx
npx -y keycloak-model-context-protocol

# Or install globally
npm install -g keycloak-model-context-protocol

Set up a Local Development Environment

If you want to develop or modify the server:

git clone <repository-url>
cd keycloak-model-context-protocol
npm install
npm run build

📚 Documentation

Configuration

Using the NPM Package (Recommended)

Configure the server in your Claude Desktop configuration file:

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

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"
      }
    }
  }
}

Available Tools

create-user

Create a new user in the specified realm. Input:

• realm: Realm name
• username: User's username
• email: User's email address
• firstName: User's first name
• lastName: User's last name

delete-user

Delete a user from the specified realm. Input:

• realm: Realm name
• userId: ID of the user to delete

list-realms

List all available realms.

list-users

List all users in the specified realm. Input:

• realm: Realm name

Development

npm run watch

Testing

Test the server using the MCP inspector:

npx -y @modelcontextprotocol/inspector npx -y keycloak-model-context-protocol

Deployment

NPM Package

This project is published to NPM on GitHub via GitHub Actions when a new version is released on GitHub.

Deployment Prerequisites

1. Create an NPM account and obtain an access token.
2. Add the NPM_TOKEN secret to your GitHub repository:
   • Go to the repository settings > Secrets.
   • Add a new secret named NPM_TOKEN.
   • Paste your NPM access token as the value.

🔧 Technical Details

Prerequisites

• Node.js 18 or higher
• A running Keycloak instance