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 nameusername: Username for the new useremail: Email address for the userfirstName: User's first namelastName: User's last name
delete-user
Deletes a user from a specified realm.
Inputs:
realm: The realm nameuserId: 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
- Create NPM account and get access token
- 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