list_users
Retrieve and filter user data from ServiceNow instances using customizable parameters like active status, department, and search queries.
Instructions
List users in ServiceNow
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| active | No | Filter by active status | |
| department | No | Filter by department | |
| limit | No | Maximum number of users to return | |
| offset | No | Offset for pagination | |
| query | No | Case-insensitive search term that matches against name, username, or email fields. Uses ServiceNow's LIKE operator for partial matching. |
Implementation Reference
- The handler function for the 'list_users' tool. It queries the ServiceNow sys_user table API with support for pagination (limit/offset), filtering by active status and department, and a search query across name, username, and email fields using LIKE operators. Returns a dict with success status, message, users list, and count.def list_users( config: ServerConfig, auth_manager: AuthManager, params: ListUsersParams, ) -> dict: """ List users from ServiceNow. Args: config: Server configuration. auth_manager: Authentication manager. params: Parameters for listing users. Returns: Dictionary containing list of users. """ api_url = f"{config.api_url}/table/sys_user" 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.department: query_parts.append(f"department={params.department}") if params.query: query_parts.append( f"^nameLIKE{params.query}^ORuser_nameLIKE{params.query}^ORemailLIKE{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)} users", "users": result, "count": len(result), } except requests.RequestException as e: logger.error(f"Failed to list users: {e}") return {"success": False, "message": f"Failed to list users: {str(e)}"}
- Pydantic model defining the input parameters for the list_users tool: limit, offset for pagination; optional filters for active status, department, and a search query.class ListUsersParams(BaseModel): """Parameters for listing users.""" limit: int = Field(10, description="Maximum number of users to return") offset: int = Field(0, description="Offset for pagination") active: Optional[bool] = Field(None, description="Filter by active status") department: Optional[str] = Field(None, description="Filter by department") query: Optional[str] = Field( None, description="Case-insensitive search term that matches against name, username, or email fields. Uses ServiceNow's LIKE operator for partial matching.", )
- src/servicenow_mcp/utils/tool_utils.py:748-754 (registration)Registration of the 'list_users' tool in the central tool_definitions dictionary used by the MCP server. Maps the tool name to its handler (list_users_tool), input schema (ListUsersParams), return type hint, description, and serialization method."list_users": ( list_users_tool, ListUsersParams, Dict[str, Any], # Expects dict "List users in ServiceNow", "raw_dict", ),
- src/servicenow_mcp/tools/__init__.py:172-173 (registration)The 'list_users' function is exported in the tools package __init__.py, making it available for import in the tool_utils registration."list_users", "create_group",
- Import of the list_users handler aliased as list_users_tool for use in tool registration.list_users as list_users_tool, )