list_groups
Retrieve and filter ServiceNow groups by active status, type, or search terms in name/description fields, with pagination controls for large datasets.
Instructions
List groups from ServiceNow with optional filtering
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| active | No | Filter by active status | |
| limit | No | Maximum number of groups to return | |
| offset | No | Offset for pagination | |
| 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 core handler function for the 'list_groups' tool. It constructs a query to the ServiceNow 'sys_user_group' table API, applies filters for limit, offset, active status, type, and search query, fetches the data, and returns a structured response with groups list.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 model defining the input parameters for the list_groups tool, including pagination (limit, offset), filters (active, query, 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)Tool registration entry in get_tool_definitions() dictionary, mapping 'list_groups' to its handler (list_groups_tool), schema (ListGroupsParams), return type hint, description, and serialization method ('raw_dict')."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:67-77 (registration)Re-export of list_groups function from user_tools in the tools package __init__.py for easy access.from servicenow_mcp.tools.user_tools import ( create_user, update_user, get_user, list_users, create_group, update_group, add_group_members, remove_group_members, list_groups, )
- src/servicenow_mcp/utils/tool_utils.py:226-227 (registration)Import alias for the list_groups handler as list_groups_tool, used in tool registration.list_groups as list_groups_tool, )