ServiceNow MCP Server

Instructions

Implementation Reference

• src/servicenow_mcp/tools/user_tools.py:417-473 (handler)

  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)}"}

• src/servicenow_mcp/tools/user_tools.py:123-134 (schema)

  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,
  )