list_client_roles

Retrieve and filter client roles in Keycloak by specifying client ID, search criteria, and pagination options to manage access permissions.

Instructions

List roles for a specific client.

Args:
    client_id: Client database ID
    first: Pagination offset
    max: Maximum results size
    search: Search string
    realm: Target realm (uses default if not specified)

Returns:
    List of client roles

Input Schema

TableJSON Schema

Name	Required	Description	Default
`client_id`	Yes
`first`	No
`max`	No
`search`	No
`realm`	No

Implementation Reference

src/tools/role_tools.py:142-174 (handler)

The core handler function for the 'list_client_roles' MCP tool. Decorated with @mcp.tool() which registers it. Takes client_id and pagination/search params, uses KeycloakClient to GET /clients/{client_id}/roles.

@mcp.tool()
async def list_client_roles(
    client_id: str,
    first: Optional[int] = None,
    max: Optional[int] = None,
    search: Optional[str] = None,
    realm: Optional[str] = None,
) -> List[Dict[str, Any]]:
    """
    List roles for a specific client.

    Args:
        client_id: Client database ID
        first: Pagination offset
        max: Maximum results size
        search: Search string
        realm: Target realm (uses default if not specified)

    Returns:
        List of client roles
    """
    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", f"/clients/{client_id}/roles", params=params, realm=realm
    )

src/tools/keycloak_client.py:59-108 (helper)

The _make_request helper method in KeycloakClient class, called by list_client_roles to perform the authenticated GET request to Keycloak 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)}")

src/main.py:22-22 (registration)
Import of role_tools module in main.py, which triggers execution of @mcp.tool() decorators to register all tools including list_client_roles with the MCP server.
```
from .tools import role_tools  # noqa: F401
```

mcp-keycloak