Keycloak MCP Server

A comprehensive Model Context Protocol (MCP) server that exposes the Keycloak Admin REST API as typed MCP tools. 299 tools covering all API categories.

Features

• Complete API coverage: All 299 Keycloak Admin REST API endpoints
• Dual transport: stdio (Claude Code) and SSE (GitHub Copilot, other MCP clients)
• Auto-authentication: Supports both password and client credentials flows with automatic token refresh
• Zero configuration tools: Each tool is self-describing with full input schemas

API Categories

Demo

(Add a GIF or screenshot here demonstrating 3 real prompts and their executed tools!)

Security & Production Recommendations

⚠️ SECURITY WARNING: This MCP Server registers all Keycloak Admin REST API endpoints (299 tools), including sensitive write operations (like creating/deleting users, resetting passwords, and managing realms). Do not use your master realm super-admin credentials in a production environment.

When attaching this MCP server to your AI Assistants, please strictly follow the Principle of Least Privilege:

1. Use Service Accounts (Client Credentials Flow): Avoid using the Password flow (KEYCLOAK_ADMIN_USERNAME / KEYCLOAK_ADMIN_PASSWORD). Instead, create a dedicated Keycloak Client with Service Accounts Enabled, and use the KEYCLOAK_CLIENT_ID and KEYCLOAK_CLIENT_SECRET.

2. Limit Target Realms: Do not attach the server to the master realm unless specifically necessary. Point KEYCLOAK_ADMIN_REALM to the exact realm your AI assistant should manage.

3. Grant Only Required Roles: Only assign the minimum necessary roles to your MCP Service Account.

   • If your LLM only needs to read data: Assign only view-users, view-clients, or view-realm.
   • If your LLM needs to manage users: Assign only manage-users.
   • Never assign admin or realm-admin roles to the AI unless you are fully aware of the risks.

4. Always Verify SSL: Keep KEYCLOAK_VERIFY_SSL=true enabled in production to prevent Man-in-the-Middle (MITM) attacks. Setting it to false is only acceptable for local development.

Examples

Once connected, you can use natural language to interact with Keycloak:

• "List all realms" → calls list_realms
• "Create a user called john in the master realm" → calls create_user
• "Show me all clients in the production realm" → calls list_clients
• "What roles does user X have?" → calls get_user_role_mappings
• "Add the admin role to the developers group" → calls add_group_realm_role_mappings

Project Structure

src/keycloak_mcp_server/
├── __init__.py          # Package entry point
├── __main__.py          # CLI entry point
├── config.py            # Environment-based configuration
├── client.py            # Async HTTP client with auto-auth
├── server.py            # MCP server setup and tool registration
└── endpoints/           # Endpoint definitions by category
    ├── __init__.py      # Base classes (EndpointDef, Param)
    ├── attack_detection.py
    ├── authentication.py
    ├── certificates.py
    ├── client_initial_access.py
    ├── client_registration_policy.py
    ├── client_role_mappings.py
    ├── client_scopes.py
    ├── clients.py
    ├── component.py
    ├── groups.py
    ├── identity_providers.py
    ├── key.py
    ├── organizations.py
    ├── protocol_mappers.py
    ├── realms.py
    ├── roles.py
    ├── roles_by_id.py
    ├── scope_mappings.py
    └── users.py

Installation

Option 1: Run directly with uvx (Recommended)

You can run the server directly without manual installation using astral's uv:

uvx keycloak-mcp-server

(When using uvx, you can pass environment variables inline or keep them in your MCP config file.)

Option 2: Install via pip

If you prefer a global or virtual environment installation:

pip install git+https://github.com/paoloamato2/keycloak-mcp-server.git

Option 3: Install from source (For development)

git clone https://github.com/paoloamato2/keycloak-mcp-server.git
cd keycloak-mcp-server
uv pip install -e .

Configuration

Set environment variables (or create a .env file based on .env.example):

# Required
export KEYCLOAK_URL=http://localhost:8080

# Authentication - Option A: Password flow
export KEYCLOAK_ADMIN_USERNAME=admin
export KEYCLOAK_ADMIN_PASSWORD=admin

# Authentication - Option B: Client credentials flow
export KEYCLOAK_CLIENT_ID=my-client
export KEYCLOAK_CLIENT_SECRET=my-secret

# Optional
export KEYCLOAK_ADMIN_REALM=master    # default: master
export KEYCLOAK_VERIFY_SSL=true       # default: true

Usage

Claude Code (stdio)

Add to your Claude Code MCP configuration (~/.claude/claude_desktop_config.json or project-level):

{
  "mcpServers": {
    "keycloak": {
      "command": "python",
      "args": ["-m", "keycloak_mcp_server"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN_USERNAME": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

Or if installed with uv:

{
  "mcpServers": {
    "keycloak": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/keycloak-mcp-server", "python", "-m", "keycloak_mcp_server"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN_USERNAME": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

GitHub Copilot (SSE)

Start the server with SSE transport:

python -m keycloak_mcp_server --transport sse --port 8080

Then configure in your GitHub Copilot MCP settings (VS Code settings.json):

{
  "github.copilot.chat.mcpServers": {
    "keycloak": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

Command Line

# stdio mode (default)
python -m keycloak_mcp_server

# SSE mode
python -m keycloak_mcp_server --transport sse --host 0.0.0.0 --port 8080

# Using the entry point
keycloak-mcp-server --transport sse --port 8080

License

MIT