list_groups
Retrieve groups from ServiceNow with filtering options for active status, type, and search terms. Supports pagination with limit and offset parameters.
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 implements the list_groups tool. It queries the ServiceNow sys_user_group table using the provided parameters for filtering, pagination, and search.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 pagination, filters for active status, type, and query.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:783-789 (registration)Registration of the list_groups tool in the central tool_definitions dictionary used by the MCP server. Includes the imported handler, 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:177-177 (registration)The list_groups tool is exported via __all__ in the tools package __init__.py for easy imports."list_groups",
- src/servicenow_mcp/utils/tool_utils.py:226-226 (registration)Import alias of the list_groups function as list_groups_tool for use in tool registration.list_groups as list_groups_tool,