Keycloak MCP

Keycloak MCP Server

A Model Context Protocol server for Keycloak administration, providing tools to manage users and realms.

Features

• Create new users in specific realms
• Delete users from realms
• List available realms
• List users in specific realms

Installation

Installing via Smithery

To install Keycloak for Claude Desktop automatically via Smithery:

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

Via NPM (Recommended)

The server is available as an NPM package:

1# Direct usage with npx
2npx -y keycloak-model-context-protocol
3
4# Or global installation
5npm install -g keycloak-model-context-protocol

Local Development Setup

If you want to develop or modify the server:

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

Configuration

Using NPM Package (Recommended)

Configure the server in your Claude Desktop configuration file:

1{
2  "mcpServers": {
3    "keycloak": {
4      "command": "npx",
5      "args": ["-y", "keycloak-model-context-protocol"],
6      "env": {
7        "KEYCLOAK_URL": "http://localhost:8080",
8        "KEYCLOAK_ADMIN": "admin",
9        "KEYCLOAK_ADMIN_PASSWORD": "admin"
10      }
11    }
12  }
13}

For Local Development

1{
2  "mcpServers": {
3    "keycloak": {
4      "command": "node",
5      "args": ["path/to/dist/index.js"],
6      "env": {
7        "KEYCLOAK_URL": "http://localhost:8080",
8        "KEYCLOAK_ADMIN": "admin",
9        "KEYCLOAK_ADMIN_PASSWORD": "admin"
10      }
11    }
12  }
13}

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

Development

1npm run watch

Testing

To test the server using MCP Inspector:

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

Deployment

NPM Package

This project is automatically published to NPM via GitHub Actions when a new release is published on GitHub.

Setup Requirements for Deployment

1. Create NPM account and get access token
2. Add NPM_TOKEN secret to GitHub repository
   • Go to repository Settings > Secrets
   • Add new secret named NPM_TOKEN
   • Paste your NPM access token as the value

Prerequisites

• Node.js 18 or higher
• Running Keycloak instance