Metadata-Version: 2.4
Name: keycloak-mcp
Version: 0.2.0
Summary: MCP server for KeyCloak Admin REST API via Service Account
Author: AIKAWA Shigechika
License-Expression: MIT
Project-URL: Homepage, https://github.com/shigechika/keycloak-mcp
Project-URL: Repository, https://github.com/shigechika/keycloak-mcp
Project-URL: Issues, https://github.com/shigechika/keycloak-mcp/issues
Keywords: keycloak,mcp,model-context-protocol,sso,authentication
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0
Requires-Dist: httpx
Dynamic: license-file

<!-- mcp-name: io.github.shigechika/keycloak-mcp -->

# keycloak-mcp

English | [日本語](README.ja.md)

MCP (Model Context Protocol) server for [KeyCloak](https://www.keycloak.org/) Admin REST API.

Uses **Client Credentials Grant** (Service Account) — no user password or TOTP required.
Infinispan-safe: does not create user sessions or use the userinfo endpoint.

## Features

### User Management

| Tool | Description |
|------|-------------|
| `count_users` | Get total user count in the realm |
| `search_users` | Search users by username, email, or name |
| `get_user` | Get detailed user information by username |
| `reset_password` | Reset a user's password |
| `reset_passwords_batch` | Reset passwords for multiple users from CSV |
| `get_user_sessions` | Get active sessions for a user (local time) |
| `logout_user` | Force logout a user by removing all sessions |

### Group Management

| Tool | Description |
|------|-------------|
| `list_user_groups` | List groups a user belongs to |
| `list_users_by_group` | List all members of a group |

### Security Monitoring

| Tool | Description |
|------|-------------|
| `get_brute_force_status` | Check if a user is locked by brute force detection |
| `get_login_failures_by_ip` | Login failure statistics by source IP (with site labels) |
| `detect_login_loops` | Detect users with rapid repeated logins (redirect loop detection) |

### Event Analytics

| Tool | Description |
|------|-------------|
| `get_events` | Get events with filters (type, username, client, IP, date). Resolves username to user ID automatically |
| `get_login_stats` | Login success/failure statistics with full pagination |
| `get_login_stats_by_hour` | Login statistics by hour (local time) |
| `get_login_stats_by_client` | Login statistics by client (SP) |
| `get_password_update_events` | Password update event history |

### Session & Client

| Tool | Description |
|------|-------------|
| `get_session_stats` | Active session count per client |
| `get_client_sessions` | Active sessions for a specific client |
| `list_clients` | List all SAML/OIDC clients |
| `get_realm_roles` | List all realm-level roles |

## Setup

```bash
# uv
uv pip install keycloak-mcp

# pip
pip install keycloak-mcp
```

Or from source:

```bash
git clone https://github.com/shigechika/keycloak-mcp.git
cd keycloak-mcp

# uv
uv sync

# pip
pip install -e .
```

## Configuration

Set the following environment variables:

| Variable | Description | Default |
|---|---|---|
| `KEYCLOAK_URL` | KeyCloak base URL (e.g., `https://sso.example.com`) | *required* |
| `KEYCLOAK_REALM` | Realm name | `master` |
| `KEYCLOAK_CLIENT_ID` | Service Account client ID | *required* |
| `KEYCLOAK_CLIENT_SECRET` | Client secret | *required* |
| `KEYCLOAK_SITES_INI` | Path to INI file for IP-to-site classification (optional) | — |

### KeyCloak Client Setup

1. Create a new client in KeyCloak Admin Console
2. Enable **Client authentication** and **Service account roles**
3. Assign realm roles: `view-users`, `view-events`, `view-clients`, `manage-users` (for password reset)

## Usage

### Claude Code

Add to `.mcp.json`:

```json
{
  "mcpServers": {
    "keycloak-mcp": {
      "type": "stdio",
      "command": "keycloak-mcp",
      "env": {
        "KEYCLOAK_URL": "https://sso.example.com",
        "KEYCLOAK_CLIENT_ID": "keycloak-mcp",
        "KEYCLOAK_CLIENT_SECRET": ""
      }
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "keycloak-mcp": {
      "command": "keycloak-mcp",
      "env": {
        "KEYCLOAK_URL": "https://sso.example.com",
        "KEYCLOAK_CLIENT_ID": "keycloak-mcp",
        "KEYCLOAK_CLIENT_SECRET": ""
      }
    }
  }
}
```

### Direct Execution

```bash
export KEYCLOAK_URL=https://sso.example.com
export KEYCLOAK_CLIENT_ID=keycloak-mcp
export KEYCLOAK_CLIENT_SECRET=your-secret
keycloak-mcp
```

## Development

```bash
git clone https://github.com/shigechika/keycloak-mcp.git
cd keycloak-mcp

# uv
uv sync --dev
uv run pytest -v
uv run ruff check .

# pip
python3 -m venv .venv
.venv/bin/pip install -e . && .venv/bin/pip install pytest pytest-cov respx ruff
.venv/bin/pytest -v
.venv/bin/ruff check .
```

## License

MIT
