keycloak-mcp 0.1.0__tar.gz

keycloak_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AIKAWA Shigechika
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

keycloak_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: keycloak-mcp
+Version: 0.1.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 |
+
+### 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 |
+
+### Event Analytics
+
+| Tool | Description |
+|------|-------------|
+| `get_events` | Get KeyCloak events with filters (type, user, date) |
+| `get_login_stats` | Login success/failure statistics with 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 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

keycloak_mcp-0.1.0/README.md

@@ -0,0 +1,168 @@
+<!-- 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 |
+
+### 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 |
+
+### Event Analytics
+
+| Tool | Description |
+|------|-------------|
+| `get_events` | Get KeyCloak events with filters (type, user, date) |
+| `get_login_stats` | Login success/failure statistics with 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 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

keycloak_mcp-0.1.0/keycloak_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""KeyCloak MCP Server — Admin REST API via Service Account."""
+
+__version__ = "0.1.0"

keycloak_mcp-0.1.0/keycloak_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for keycloak-mcp MCP server."""
+
+from .server import mcp
+
+mcp.run(transport="stdio")

keycloak_mcp-0.1.0/keycloak_mcp/auth.py

@@ -0,0 +1,58 @@
+"""Token management for KeyCloak Service Account (Client Credentials Grant)."""
+
+import os
+import time
+
+import httpx
+
+
+class TokenManager:
+    """Manage KeyCloak access tokens with automatic refresh.
+
+    Tokens are refreshed 30 seconds before expiry to avoid mid-request failures.
+    """
+
+    def __init__(self):
+        self.url = os.environ["KEYCLOAK_URL"].rstrip("/")
+        self.realm = os.environ.get("KEYCLOAK_REALM", "master")
+        self.client_id = os.environ["KEYCLOAK_CLIENT_ID"]
+        self.client_secret = os.environ["KEYCLOAK_CLIENT_SECRET"]
+        self._token = None
+        self._expires_at = 0
+
+    @property
+    def token_endpoint(self) -> str:
+        """Return the OIDC token endpoint URL."""
+        return f"{self.url}/realms/{self.realm}/protocol/openid-connect/token"
+
+    @property
+    def admin_base(self) -> str:
+        """Return the Admin REST API base URL."""
+        return f"{self.url}/admin/realms/{self.realm}"
+
+    def get_token(self) -> str:
+        """Return a valid access token, refreshing if needed."""
+        if self._token and time.time() < self._expires_at - 30:
+            return self._token
+        return self._refresh()
+
+    def _refresh(self) -> str:
+        """Fetch a new token via Client Credentials Grant."""
+        resp = httpx.post(
+            self.token_endpoint,
+            data={
+                "grant_type": "client_credentials",
+                "client_id": self.client_id,
+                "client_secret": self.client_secret,
+            },
+            timeout=10,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        self._token = data["access_token"]
+        self._expires_at = time.time() + data.get("expires_in", 300)
+        return self._token
+
+    def headers(self) -> dict:
+        """Return Authorization headers with a valid Bearer token."""
+        return {"Authorization": f"Bearer {self.get_token()}"}

keycloak_mcp-0.1.0/keycloak_mcp/client.py

@@ -0,0 +1,163 @@
+"""KeyCloak Admin REST API client."""
+
+from typing import Any
+
+import httpx
+
+from .auth import TokenManager
+
+
+class KeyCloakClient:
+    """Thin wrapper around the KeyCloak Admin REST API."""
+
+    def __init__(self):
+        self.auth = TokenManager()
+        self._http = httpx.Client(timeout=30)
+
+    def _get(self, path: str, params: dict | None = None) -> Any:
+        """GET request to Admin API."""
+        url = f"{self.auth.admin_base}{path}"
+        resp = self._http.get(url, headers=self.auth.headers(), params=params or {})
+        resp.raise_for_status()
+        return resp.json()
+
+    def _put(self, path: str, json: dict | None = None) -> int:
+        """PUT request to Admin API. Returns status code."""
+        url = f"{self.auth.admin_base}{path}"
+        resp = self._http.put(url, headers=self.auth.headers(), json=json or {})
+        resp.raise_for_status()
+        return resp.status_code
+
+    # --- Users ---
+
+    def count_users(self) -> int:
+        """Return total user count."""
+        return self._get("/users/count")
+
+    def search_users(self, query: str, max_results: int = 20) -> list[dict]:
+        """Search users by username, email, or name."""
+        return self._get("/users", {"search": query, "max": max_results})
+
+    def get_user(self, user_id: str) -> dict:
+        """Get user by ID."""
+        return self._get(f"/users/{user_id}")
+
+    def get_user_by_username(self, username: str) -> dict | None:
+        """Get user by exact username. Returns None if not found."""
+        users = self._get("/users", {"username": username, "exact": "true"})
+        return users[0] if users else None
+
+    def reset_password(self, user_id: str, password: str, temporary: bool = False) -> int:
+        """Reset a user's password."""
+        return self._put(
+            f"/users/{user_id}/reset-password",
+            {"type": "password", "value": password, "temporary": temporary},
+        )
+
+    def get_user_sessions(self, user_id: str) -> list[dict]:
+        """Get active sessions for a user."""
+        return self._get(f"/users/{user_id}/sessions")
+
+    def get_user_roles(self, user_id: str) -> dict:
+        """Get role mappings for a user."""
+        return self._get(f"/users/{user_id}/role-mappings")
+
+    def get_user_groups(self, user_id: str) -> list[dict]:
+        """Get groups a user belongs to."""
+        return self._get(f"/users/{user_id}/groups")
+
+    # --- Brute Force ---
+
+    def get_brute_force_status(self, user_id: str) -> dict:
+        """Get brute force detection status for a user."""
+        return self._get(f"/attack-detection/brute-force/users/{user_id}")
+
+    # --- Groups ---
+
+    def list_groups(self, max_results: int = 100) -> list[dict]:
+        """List all groups."""
+        return self._get("/groups", {"max": max_results})
+
+    def get_group_members(self, group_id: str, max_results: int = 100) -> list[dict]:
+        """Get members of a group."""
+        return self._get(f"/groups/{group_id}/members", {"max": max_results})
+
+    # --- Events ---
+
+    def get_events(
+        self,
+        event_type: str | None = None,
+        user: str | None = None,
+        date_from: str | None = None,
+        date_to: str | None = None,
+        max_results: int = 100,
+    ) -> list[dict]:
+        """Get events with optional filters (single page)."""
+        params: dict[str, Any] = {"max": max_results}
+        if event_type:
+            params["type"] = event_type
+        if user:
+            params["user"] = user
+        if date_from:
+            params["dateFrom"] = date_from
+        if date_to:
+            params["dateTo"] = date_to
+        return self._get("/events", params)
+
+    def get_events_all(
+        self,
+        event_type: str | None = None,
+        user: str | None = None,
+        date_from: str | None = None,
+        date_to: str | None = None,
+        page_size: int = 1000,
+    ) -> list[dict]:
+        """Get all events with automatic pagination."""
+        params: dict[str, Any] = {"max": page_size, "first": 0}
+        if event_type:
+            params["type"] = event_type
+        if user:
+            params["user"] = user
+        if date_from:
+            params["dateFrom"] = date_from
+        if date_to:
+            params["dateTo"] = date_to
+        all_events: list[dict] = []
+        while True:
+            page = self._get("/events", params)
+            all_events.extend(page)
+            if len(page) < page_size:
+                break
+            params["first"] += page_size
+        return all_events
+
+    # --- Sessions ---
+
+    def get_session_stats(self) -> list[dict]:
+        """Get client session statistics."""
+        return self._get("/client-session-stats")
+
+    # --- Clients ---
+
+    def list_clients(self, max_results: int = 100) -> list[dict]:
+        """List all clients."""
+        return self._get("/clients", {"max": max_results})
+
+    def get_client(self, client_id: str) -> dict:
+        """Get client by internal ID."""
+        return self._get(f"/clients/{client_id}")
+
+    def get_client_by_client_id(self, client_id: str) -> dict | None:
+        """Get client by clientId (not internal UUID)."""
+        clients = self._get("/clients", {"clientId": client_id})
+        return clients[0] if clients else None
+
+    def get_client_sessions(self, internal_id: str, max_results: int = 100) -> list[dict]:
+        """Get active sessions for a client."""
+        return self._get(f"/clients/{internal_id}/user-sessions", {"max": max_results})
+
+    # --- Roles ---
+
+    def get_realm_roles(self) -> list[dict]:
+        """List realm roles."""
+        return self._get("/roles")