home / mcp / keycloak mcp server

Keycloak MCP Server

Provides an MCP interface to manage Keycloak realms, users, clients, and groups via standardized actions.

Installation

Add the following to your MCP client configuration file.

Configuration

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

You can manage Keycloak users and realms through a standardized MCP interface built for Keycloak. This server lets you perform common identity-management tasks with a consistent set of endpoints, making it easier to integrate Keycloak into your MCP-driven workflows.

How to use

You interact with the Keycloak MCP Server through an MCP client. With the server running, you can create, delete, and list users, realms, clients, groups, and their roles. You can also assign client roles to users and add users to groups. Use the available tools to perform these actions in real time against your Keycloak instance.

How to install

Prerequisites: you need Node.js (latest LTS is recommended) and npm installed. You also need a running Keycloak instance to connect to.

# Install and run using npx (no local install required)
npx -y keycloak-mcp --keycloak-url <Keycloak Instance URL> --keycloak-admin <Admin Username> --keycloak-admin-password <Admin Password>

# Or install globally and run
npm install -g keycloak-mcp@latest
keycloak-mcp --keycloak-url <Keycloak Instance URL> --keycloak-admin <Admin Username> --keycloak-admin-password <Admin Password>

Configuration

Configure the server by providing the Keycloak connection details as environment variables or CLI arguments. The following environment variables are recognized by the server when running locally or via a config file.

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

Security and access

Keep admin credentials secure. Use the recommended Keycloak admin account with the minimum required permissions for MCP operations. Consider using a dedicated Keycloak service account with restricted access for MCP tasks and rotate credentials regularly.

Troubleshooting and tips

If you encounter connection issues, verify that the Keycloak URL is reachable from the MCP server host and that the admin credentials provided have sufficient permissions. Check that the Keycloak Admin Client library is present and that the MCP server has network access to Keycloak.

Notes and capabilities

The server exposes a set of tools to manage Keycloak resources: create-user, delete-user, list-realms, list-users, list-clients, list-groups, list-client-roles, assign-client-role-to-user, and add-user-to-group. Each tool accepts the required inputs described in its usage and operates against the connected Keycloak instance.

Available tools overview

- create-user: Creates a new user in a specified realm. Inputs: realm, username, email, firstName, lastName. - delete-user: Deletes a user from a specified realm. Inputs: realm, userId. - list-realms: Lists all available realms. - list-users: Lists all users in a specified realm. Inputs: realm. - list-clients: Lists all clients in a specified realm. Inputs: realm. - list-groups: Lists all groups in a specified realm. Inputs: realm. - list-client-roles: Lists all roles for a specific client in a realm. Inputs: realm, clientUniqueId. - assign-client-role-to-user: Assigns a client role to a user. Inputs: realm, userId, clientUniqueId, roleName. - add-user-to-group: Adds a user to a group. Inputs: realm, userId, groupId.

Example configuration snippets

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": ["-y", "keycloak-mcp"],
      "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 with provided username, email, first name, and last name.

delete-user

Deletes a user from a specified realm by user ID.

list-realms

Lists all available realms in the Keycloak instance.

list-users

Lists all users within a specified realm.

list-clients

Lists all clients within a specified realm.

list-groups

Lists all groups within a specified realm.

list-client-roles

Lists all roles for a specific client in a realm.

assign-client-role-to-user

Assigns a client role to a specific user in a realm.

add-user-to-group

Adds a user to a specific group within a realm.