list_groups
Retrieve and manage group listings within a Keycloak realm using pagination, search, and customizable parameters to streamline access control.
Instructions
List all groups in the realm.
Args:
first: Pagination offset
max: Maximum results size
search: Search string
realm: Target realm (uses default if not specified)
Returns:
List of groups
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| first | No | ||
| max | No | ||
| realm | No | ||
| search | No |
Implementation Reference
- src/tools/group_tools.py:9-36 (handler)The core handler implementation for the 'list_groups' MCP tool. Decorated with @mcp.tool() which handles registration and schema from type hints/docstring. Fetches groups from Keycloak API using KeycloakClient._make_request with optional pagination, search, and realm parameters.@mcp.tool() async def list_groups( first: Optional[int] = None, max: Optional[int] = None, search: Optional[str] = None, realm: Optional[str] = None, ) -> List[Dict[str, Any]]: """ List all groups in the realm. Args: first: Pagination offset max: Maximum results size search: Search string realm: Target realm (uses default if not specified) Returns: List of groups """ params = {} if first is not None: params["first"] = first if max is not None: params["max"] = max if search: params["search"] = search return await client._make_request("GET", "/groups", params=params, realm=realm)
- src/main.py:18-24 (registration)Import statements for all tool modules including group_tools. Importing these modules executes the @mcp.tool() decorators, registering the 'list_groups' tool (and others) with the MCP server.from . import tools # noqa: F401 from .tools import user_tools # noqa: F401 from .tools import client_tools # noqa: F401 from .tools import realm_tools # noqa: F401 from .tools import role_tools # noqa: F401 from .tools import group_tools # noqa: F401
- src/tools/keycloak_client.py:59-108 (helper)The _make_request helper method in KeycloakClient, directly called by list_groups handler to perform authenticated HTTP requests to the Keycloak Admin API.async def _make_request( self, method: str, endpoint: str, data: Optional[Dict] = None, params: Optional[Dict] = None, skip_realm: bool = False, realm: Optional[str] = None, ) -> Any: """Make authenticated request to Keycloak API""" if skip_realm: url = f"{self.server_url}/auth/admin{endpoint}" else: # Use provided realm or fall back to configured realm target_realm = realm if realm is not None else self.realm_name url = f"{self.server_url}/auth/admin/realms/{target_realm}{endpoint}" try: client = await self._ensure_client() headers = await self._get_headers() response = await client.request( method=method, url=url, headers=headers, json=data, params=params, ) # If token expired, refresh and retry if response.status_code == 401: await self._get_token() headers = await self._get_headers() response = await client.request( method=method, url=url, headers=headers, json=data, params=params, ) response.raise_for_status() if response.content: return response.json() return None except httpx.RequestError as e: raise Exception(f"Keycloak API request failed: {str(e)}")