Keycloak MCP

What is Keycloak MCP Server?

Keycloak MCP Server is a Model Context Protocol (MCP) server designed to facilitate the administration of Keycloak users and realms through natural language interaction. It integrates seamlessly with AI tools like Claude Desktop, allowing for automated user operations within Keycloak.

How to use Keycloak MCP Server?

Keycloak MCP Server can be installed and used in several ways:

• Via Smithery: For automatic installation with Claude Desktop, use the command: npx -y @smithery/cli install keycloak-model-context-protocol --client claude.
• Via NPM (Recommended):
  • Direct usage: npx -y keycloak-model-context-protocol
  • Global installation: npm install -g keycloak-model-context-protocol

After installation, configure the server in your Claude Desktop configuration file by setting mcpServers with the appropriate command and environment variables for your Keycloak instance (e.g., KEYCLOAK_URL, KEYCLOAK_ADMIN, KEYCLOAK_ADMIN_PASSWORD).

Key Features of Keycloak MCP Server

Keycloak MCP Server provides the following core functionalities:

• User Management: Create, delete, and list users in specific realms.
• Realm Management: List available realms.
• AI Integration: Enables natural language interaction with Keycloak through MCP, allowing AI tools to manage users and realms.
• Easy Installation: Available via Smithery and NPM for convenient setup.

Use Cases of Keycloak MCP Server

• Automated User Provisioning: Automatically create new users in Keycloak realms based on natural language commands from AI assistants.
• Streamlined User Deprovisioning: Efficiently delete users from Keycloak through AI-driven commands.
• AI-Powered Auditing: Quickly list users and realms for auditing purposes using natural language queries.
• Integration with AI Workflows: Embed Keycloak user and realm management into broader AI-driven automation workflows.

FAQ about Keycloak MCP Server

Q: What are the prerequisites for running Keycloak MCP Server? A: You need Node.js 18 or higher and a running Keycloak instance.

Q: How can I configure Keycloak MCP Server? A: Configuration is done within your Claude Desktop configuration file, where you specify the command to run the server and environment variables for your Keycloak instance.

Q: Can I use Keycloak MCP Server for local development? A: Yes, you can set up a local development environment by cloning the repository, installing dependencies, and building the project. Configuration for local development involves specifying the path to the compiled index.js file.

Q: How can I test Keycloak MCP Server? A: You can test the server using MCP Inspector with the command: npx -y @modelcontextprotocol/inspector npx -y keycloak-model-context-protocol.

Q: How is Keycloak MCP Server deployed? A: The project is automatically published to NPM via GitHub Actions when a new release is published on GitHub, provided the NPM_TOKEN secret is configured in the repository.

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:

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

Via NPM (Recommended)

The server is available as an NPM package:

# Direct usage with npx
npx -y keycloak-model-context-protocol

# Or global installation
npm install -g keycloak-model-context-protocol

Local Development Setup

If you want to develop or modify the server:

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

Configuration

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

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

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

npm run watch

Testing

To test the server using MCP Inspector:

npx -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