list_catalog_item_variables

Retrieve variables associated with a ServiceNow catalog item to configure request forms and automate workflows. Supports pagination and detailed variable information.

Instructions

List catalog item variables

Input Schema

TableJSON Schema

Name	Required	Description
`catalog_item_id`	Yes	The sys_id of the catalog item
`include_details`	No	Whether to include detailed information about each variable
`limit`	No	Maximum number of variables to return
`offset`	No	Offset for pagination

Implementation Reference

src/servicenow_mcp/tools/catalog_variables.py:154-214 (handler)

The handler function that executes the tool logic: queries ServiceNow's item_option_new table for variables of a catalog item, supports pagination and details flag.

def list_catalog_item_variables(
    config: ServerConfig,
    auth_manager: AuthManager,
    params: ListCatalogItemVariablesParams,
) -> ListCatalogItemVariablesResponse:
    """
    List all variables (form fields) for a catalog item.

    Args:
        config: Server configuration.
        auth_manager: Authentication manager.
        params: Parameters for listing catalog item variables.

    Returns:
        Response with a list of variables for the catalog item.
    """
    # Build query parameters
    query_params = {
        "sysparm_query": f"cat_item={params.catalog_item_id}^ORDERBYorder",
    }
    
    if params.limit:
        query_params["sysparm_limit"] = params.limit
    if params.offset:
        query_params["sysparm_offset"] = params.offset
    
    # Include all fields if detailed info is requested
    if params.include_details:
        query_params["sysparm_display_value"] = "true"
        query_params["sysparm_exclude_reference_link"] = "false"
    else:
        query_params["sysparm_fields"] = "sys_id,name,type,question_text,order,mandatory"

    api_url = f"{config.instance_url}/api/now/table/item_option_new"

    # 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 ListCatalogItemVariablesResponse(
            success=True,
            message=f"Retrieved {len(result)} variables for catalog item",
            variables=result,
            count=len(result),
        )

    except requests.RequestException as e:
        logger.error(f"Failed to list catalog item variables: {e}")
        return ListCatalogItemVariablesResponse(
            success=False,
            message=f"Failed to list catalog item variables: {str(e)}",
        )

src/servicenow_mcp/tools/catalog_variables.py:47-54 (schema)

Pydantic model defining the input parameters for the tool: catalog_item_id (required), include_details, limit, offset.

class ListCatalogItemVariablesParams(BaseModel):
    """Parameters for listing catalog item variables."""

    catalog_item_id: str = Field(..., description="The sys_id of the catalog item")
    include_details: bool = Field(True, description="Whether to include detailed information about each variable")
    limit: Optional[int] = Field(None, description="Maximum number of variables to return")
    offset: Optional[int] = Field(None, description="Offset for pagination")

src/servicenow_mcp/tools/catalog_variables.py:56-63 (schema)

Pydantic model for the tool's response: success, message, variables list, count.

class ListCatalogItemVariablesResponse(BaseModel):
    """Response from listing catalog item variables."""

    success: bool = Field(..., description="Whether the operation was successful")
    message: str = Field(..., description="Message describing the result")
    variables: List[Dict[str, Any]] = Field([], description="List of variables")
    count: int = Field(0, description="Total number of variables found")

src/servicenow_mcp/utils/tool_utils.py:418-424 (registration)
Registration of the tool in the central tool_definitions dictionary used by the MCP server: maps name to (handler, input_schema, return_type, description, serialization).
```
"list_catalog_item_variables": (
    list_catalog_item_variables_tool,
    ListCatalogItemVariablesParams,
    Dict[str, Any],  # Expects dict
    "List catalog item variables",
    "dict",  # Tool returns Pydantic model
),
```
src/servicenow_mcp/tools/__init__.py:18-22 (registration)
Import of the handler function into the tools package namespace, exposing it for use in tool_utils.py.
```
from servicenow_mcp.tools.catalog_variables import (
    create_catalog_item_variable,
    list_catalog_item_variables,
    update_catalog_item_variable,
)
```

ServiceNow MCP Server