Keycloak MCP Server

What is Keycloak MCP Server about?

The server exposes Model Context Protocol tools that interact with a running Keycloak instance, allowing AI assistants and other MCP clients to manage users and realms programmatically.

How to use Keycloak MCP Server?

1. Installation – install via npm (recommended) or Smithery:

   npx -y keycloak-model-context-protocol
   

2. Configuration – add an entry to the Claude Desktop (or other MCP client) configuration:

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

3. Running – start the server through the configured command; MCP clients can now invoke the provided tools.

Key features of Keycloak MCP Server

• Create User – add a new user to a specified realm with username, email, first name, and last name.
• Delete User – remove a user from a realm by user ID.
• List Realms – retrieve all available realms.
• List Users – enumerate users within a given realm.
• Easy npm installation – single‑command setup with npx.
• Smithery integration – one‑click deployment for Claude Desktop.
• TypeScript codebase – strong typing and easy extensibility.

Use cases of Keycloak MCP Server

• Automated onboarding – AI assistants can create user accounts when new employees are added to HR systems.
• Self‑service account cleanup – periodic scripts trigger the delete-user tool to remove inactive accounts.
• Dynamic realm discovery – tools can list realms to adapt to multi‑tenant environments.
• Integration testing – test suites invoke the MCP tools to set up and tear down test users.

FAQ from the Keycloak MCP Server

Q: Which Node version is required? A: Node.js 18 or higher.

Q: Do I need a running Keycloak instance? A: Yes, the server communicates with Keycloak via its admin REST API; configure KEYCLOAK_URL accordingly.

Q: Can I run the server locally for development? A: Clone the repository, run npm install && npm run build, then start with node dist/index.js or via the npx command.

Q: How are credentials secured? A: Provide admin credentials through environment variables; avoid committing them to source control.

Q: Is there a testing tool? A: Yes, use the Model Context Protocol Inspector: npx -y @modelcontextprotocol/inspector npx -y keycloak-model-context-protocol.

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