# Keycloak Mcp Server

> A complete Model Context Protocol (MCP) server for Keycloak 26.x

- **Type:** MCP server
- **Install:** `agentstack add mcp-paoloamato2-keycloak-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [paoloamato2](https://agentstack.voostack.com/s/paoloamato2)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [paoloamato2](https://github.com/paoloamato2)
- **Source:** https://github.com/paoloamato2/keycloak-mcp-server

## Install

```sh
agentstack add mcp-paoloamato2-keycloak-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

| Category | Tools |
|---|---|
| Attack Detection | 3 |
| Authentication Management | 38 |
| Client Certificates | 6 |
| Client Initial Access | 3 |
| Client Registration Policy | 1 |
| Client Role Mappings | 10 |
| Client Scopes | 10 |
| Clients | 33 |
| Components | 6 |
| Groups | 11 |
| Identity Providers | 15 |
| Keys | 2 |
| Organizations | 13 |
| Protocol Mappers | 14 |
| Realms Admin | 37 |
| Roles | 28 |
| Roles by ID | 10 |
| Scope Mappings | 29 |
| Users | 30 |
| **Total** | **299** |

## Demo

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

## Installation

### Option 1: Run directly with `uvx` (Recommended)
You can run the server directly without manual installation using astral's `uv`:
```bash
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:
```bash
pip install git+https://github.com/paoloamato2/keycloak-mcp-server.git
```

### Option 3: Install from source (For development)
```bash
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`):

```bash
# 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):

```json
{
  "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:

```json
{
  "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:

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

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

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

### Command Line

```bash
# 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
```

## 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
```

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [paoloamato2](https://github.com/paoloamato2)
- **Source:** [paoloamato2/keycloak-mcp-server](https://github.com/paoloamato2/keycloak-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-paoloamato2-keycloak-mcp-server
- Seller: https://agentstack.voostack.com/s/paoloamato2
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.