keycloak-model-context-protocol

This MCP server provides a Model Context Protocol interface for managing Keycloak realms and users. It exposes a set of tools that let you create users within a specific realm, delete users by ID, list available realms, and list users within a realm. The server is designed to be run as a background MCP service and can be wired into Claude Desktop or other MCP clients. Use the available tools by invoking the corresponding MCP commands and supplying the required inputs such as realm names, usernames, emails, and user IDs. The configuration example shows how to run the server via npx and supply environment variables for connecting to a local Keycloak instance. Real-world usage typically involves pointing the server at your Keycloak host, providing admin credentials, and then issuing tool invocations to manage identities within your realms.

Prerequisites:

• Node.js 18 or higher
• npm (included with Node.js)
• Access to a Keycloak instance for testing (optional for local development)

Installation steps:

1. Install the MCP server package globally or run via npx:

   • Global installation (recommended for persistent usage): npm install -g keycloak-model-context-protocol
   • Run directly with npx (no global install): npx -y keycloak-model-context-protocol

2. If you want to develop or contribute locally: git clone <repository-url> cd keycloak-model-context-protocol npm install npm run build

3. Start the MCP server (example using npx): npx -y keycloak-model-context-protocol

4. Configure Claude Desktop or your MCP client to point to the server using the provided mcp_config example in this document.

Notes and tips:

• Ensure Keycloak is reachable at the configured KEYCLOAK_URL and that the admin credentials (KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD) are correct.
• When running in production, avoid hardcoding credentials; use a secure secrets store or environment management.
• The server supports common MCP workflows: create-user, delete-user, list-realms, and list-users. Use the inputs described in the README for each tool.
• If you upgrade Keycloak or the MCP server, revalidate the inputs and ensure the environment variables remain valid.
• For local development, you can point to a local built distribution by modifying the Node.js launch path in the configuration (e.g., path/to/dist/index.js).
• If you encounter connectivity issues, verify that the Keycloak admin API is accessible from the host running the MCP server and that CORS or network policies are not blocking requests.