list_groups
Retrieve and filter groups from ServiceNow using parameters like active status, group type, or search terms for group name and description. Supports pagination with limit and offset options.
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
- Implementation of the list_groups tool handler function that queries ServiceNow's sys_user_group table with filtering and pagination.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, filters for active, 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:783-789 (registration)Registration entry for the 'list_groups' tool in the get_tool_definitions dictionary, linking the aliased handler function, input 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-177 (registration)Re-export of list_groups in the tools __init__.py for convenient import.list_groups, ) from servicenow_mcp.tools.workflow_tools import ( activate_workflow, add_workflow_activity, create_workflow, deactivate_workflow, delete_workflow_activity, get_workflow_activities, get_workflow_details, list_workflow_versions, list_workflows, reorder_workflow_activities, update_workflow, update_workflow_activity, ) # from servicenow_mcp.tools.problem_tools import create_problem, update_problem # from servicenow_mcp.tools.request_tools import create_request, update_request __all__ = [ # Incident tools "create_incident", "update_incident", "add_comment", "resolve_incident", "list_incidents", # Catalog tools "list_catalog_items", "get_catalog_item", "list_catalog_categories", "create_catalog_category", "update_catalog_category", "move_catalog_items", "get_optimization_recommendations", "update_catalog_item", "create_catalog_item_variable", "list_catalog_item_variables", "update_catalog_item_variable", # Change management tools "create_change_request", "update_change_request", "list_change_requests", "get_change_request_details", "add_change_task", "submit_change_for_approval", "approve_change", "reject_change", # Workflow management tools "list_workflows", "get_workflow_details", "list_workflow_versions", "get_workflow_activities", "create_workflow", "update_workflow", "activate_workflow", "deactivate_workflow", "add_workflow_activity", "update_workflow_activity", "delete_workflow_activity", "reorder_workflow_activities", # Changeset tools "list_changesets", "get_changeset_details", "create_changeset", "update_changeset", "commit_changeset", "publish_changeset", "add_file_to_changeset", # Script Include tools "list_script_includes", "get_script_include", "create_script_include", "update_script_include", "delete_script_include", # Knowledge Base tools "create_knowledge_base", "list_knowledge_bases", "create_category", "list_categories", "create_article", "update_article", "publish_article", "list_articles", "get_article", # User management tools "create_user", "update_user", "get_user", "list_users", "create_group", "update_group", "add_group_members", "remove_group_members", "list_groups",
- Import alias for the list_groups function as list_groups_tool used in tool registration.from servicenow_mcp.tools.user_tools import ( list_groups as list_groups_tool,