Keycloak Model Context Protocol

🚀 Keycloak MCP Server

A Model Context Protocol (MCP) server for managing Keycloak administrative users, offering features such as creating and deleting users, and viewing realms.

✨ Features

• Create new users in a specific realm.
• Delete users from a realm.
• List available realms.
• List users within a specified realm.

📦 Installation

Install via Smithery

Automatically install the Keycloak Model Context Protocol using Smithery:

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

Via NPM (Recommended)

The server is available as an NPM package:

# Use npx directly
npx -y keycloak-model-context-protocol

# Or install globally
npm install -g keycloak-model-context-protocol

Set up a Local Development Environment

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

💻 Usage Examples

create-user

Create a new user in the specified realm. Input Parameters:

• realm: Realm name
• username: User's username
• email: User's email address
• firstName: User's first name
• lastName: User's last name

delete-user

Delete a user from the specified realm. Input Parameters:

• realm: Realm name
• userId: ID of the user to be deleted

list-realms

List all available realms.

list-users

List all users in the specified realm. Input Parameters:

• realm: Realm name

🔧 Development

npm run watch

🧪 Testing

Test the server using the 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 version is released on GitHub.

Preparation before Deployment

1. Create an NPM account and obtain an access token.
2. Add NPM_TOKEN as a secret to your GitHub repository:
   • Go to the repository settings > Secrets.
   • Add a new secret named NPM_TOKEN.
   • Paste your NPM access token as the value.

⚙️ Prerequisites

• Node.js 18 or higher
• A running Keycloak instance