list_users
Retrieve and filter users in Keycloak realms using pagination, search queries, and attribute filters to manage identity access.
Instructions
List users in the realm.
Args:
first: Pagination offset
max: Maximum results size (defaults to 100)
search: Search string for username, first/last name, or email
username: Username filter
email: Email filter
enabled: Filter by enabled/disabled users
realm: Target realm (uses default if not specified)
Returns:
List of user objectsInput Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| first | No | ||
| max | No | ||
| search | No | ||
| username | No | ||
| No | |||
| enabled | No | ||
| realm | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/tools/user_tools.py:9-48 (handler)The list_users tool handler, registered via @mcp.tool() decorator. It constructs query parameters from inputs and fetches the user list from Keycloak API using the KeycloakClient instance.
@mcp.tool() async def list_users( first: Optional[int] = None, max: Optional[int] = None, search: Optional[str] = None, username: Optional[str] = None, email: Optional[str] = None, enabled: Optional[bool] = None, realm: Optional[str] = None, ) -> List[Dict[str, Any]]: """ List users in the realm. Args: first: Pagination offset max: Maximum results size (defaults to 100) search: Search string for username, first/last name, or email username: Username filter email: Email filter enabled: Filter by enabled/disabled users realm: Target realm (uses default if not specified) Returns: List of user objects """ params = {} if first is not None: params["first"] = first if max is not None: params["max"] = max if search: params["search"] = search if username: params["username"] = username if email: params["email"] = email if enabled is not None: params["enabled"] = str(enabled).lower() return await client._make_request("GET", "/users", params=params, realm=realm)