list_groups
Retrieve ServiceNow groups with filtering options for active status, type, or search terms to manage user permissions and access control.
Instructions
List groups from ServiceNow with optional filtering
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of groups to return | |
| offset | No | Offset for pagination | |
| active | No | Filter by active status | |
| query | No | Case-insensitive search term that matches against group name or description fields. Uses ServiceNow's LIKE operator for partial matching. | |
| type | No | Filter by group type |
Implementation Reference
- The handler function that executes the list_groups tool logic. It queries the ServiceNow sys_user_group table API with pagination, filtering by active, type, and search query, returning a dictionary with success status, message, groups list, and count.
def list_groups( config: ServerConfig, auth_manager: AuthManager, params: ListGroupsParams, ) -> dict: """ List groups from ServiceNow. Args: config: Server configuration. auth_manager: Authentication manager. params: Parameters for listing groups. Returns: Dictionary containing list of groups. """ api_url = f"{config.api_url}/table/sys_user_group" query_params = { "sysparm_limit": str(params.limit), "sysparm_offset": str(params.offset), "sysparm_display_value": "true", } # Build query query_parts = [] if params.active is not None: query_parts.append(f"active={str(params.active).lower()}") if params.type: query_parts.append(f"type={params.type}") if params.query: query_parts.append(f"^nameLIKE{params.query}^ORdescriptionLIKE{params.query}") if query_parts: query_params["sysparm_query"] = "^".join(query_parts) # Make request try: response = requests.get( api_url, params=query_params, headers=auth_manager.get_headers(), timeout=config.timeout, ) response.raise_for_status() result = response.json().get("result", []) return { "success": True, "message": f"Found {len(result)} groups", "groups": result, "count": len(result), } except requests.RequestException as e: logger.error(f"Failed to list groups: {e}") return {"success": False, "message": f"Failed to list groups: {str(e)}"} - Pydantic BaseModel defining the input parameters for the list_groups tool, including limit, offset, active filter, query, and type.
class ListGroupsParams(BaseModel): """Parameters for listing groups.""" limit: int = Field(10, description="Maximum number of groups to return") offset: int = Field(0, description="Offset for pagination") active: Optional[bool] = Field(None, description="Filter by active status") query: Optional[str] = Field( None, description="Case-insensitive search term that matches against group name or description fields. Uses ServiceNow's LIKE operator for partial matching.", ) type: Optional[str] = Field(None, description="Filter by group type") - src/servicenow_mcp/utils/tool_utils.py:829-835 (registration)The tool registration entry in get_tool_definitions() function, associating 'list_groups' name with the handler function, schema, return type hint, description, and serialization method.
"list_groups": ( list_groups_tool, ListGroupsParams, Dict[str, Any], # Expects dict "List groups from ServiceNow with optional filtering", "raw_dict", ), - src/servicenow_mcp/tools/__init__.py:76-76 (registration)Re-export of the list_groups function from user_tools.py for convenient access across the tools module.
list_groups,