export_shopping_list

Export a shopping list for a saved meal plan with automatic ingredient aggregation, unit conversion, and per-person rule warnings. Supports multiple export formats for different use cases.

Input Schema

Parameter	Type	Required	Default	Description
`planId`	string (UUID)	Yes	-	Meal plan ID to generate shopping list for
`format`	enum	No	`"markdown"`	Output format: `"json"`, `"csv"`, `"markdown"`, or `"text"`
`groupBy`	enum	No	`"aisle"`	Grouping strategy: `"aisle"`, `"recipe"`, or `"category"`
`includeStaples`	boolean	No	`false`	Include kitchen staples (salt, pepper, oil). Distinct from the pantry category.
`includePantryItems`	boolean	No	-	Deprecated alias for `includeStaples`
`includeRuleWarnings`	boolean	No	`true`	Include per-person rule warnings for shoppers
`timeZone`	string	No	kitchen TZ	IANA timezone for the markdown/text Generated line (always labeled)

Output Schema

{
  format: string,
  list: ShoppingListData, // structured object; never a JSON string
  content?: string,       // markdown / csv / text only; omitted for json
  itemCount: number,
  warnings: Array<{
    ingredient: string,
    personName: string,
    note: string
  }>
}

MCP tools/call also sets structuredContent to this object. Do not JSON.parse a string stuffed in content to get the list - read structuredContent.list (or list after one parse of the text JSON for format: "json").

Format Examples

Markdown (default)

# Shopping List
 
**Week Starting:** 2026-10-12
**Generated:** Oct 12, 2026, 4:00 PM CDT
 
## Produce
 
- [ ] 2 cups cherry tomatoes (Grilled Chicken Salad)
- [x] 1 head romaine lettuce (Grilled Chicken Salad)
 
## Meat
 
- [ ] 2 lbs chicken breast (Grilled Chicken Salad)
 
## Other
 
- [ ] paper towels
 
## ⚠️ Warnings
 
- **Child B**: parmesan cheese - Contains dairy (parmesan cheese), and Child B usually skips this

JSON

{
  "mealPlanId": "2d8f1a6b-5c4e-4a91-9c0e-7c2a1e8f4b3d",
  "weekStart": "2026-10-12",
  "groupBy": "aisle",
  "includeStaples": false,
  "includePantryItems": false,
  "itemCount": 2,
  "ingredients": [
    {
      "key": "chicken-breast",
      "name": "chicken breast",
      "quantity": 2,
      "unit": "lb",
      "aisle": "Meat",
      "category": "protein",
      "isStaple": false,
      "isPantryItem": false,
      "recipes": [
        {
          "recipeId": "49e5fbdd-b252-4638-a1b4-e3a5cba25c46",
          "recipeTitle": "Grilled Chicken Salad",
          "quantity": 2,
          "unit": "lb"
        }
      ]
    }
  ],
  "sections": [
    {
      "name": "Meat",
      "items": [
        {
          "key": "chicken-breast",
          "name": "chicken breast",
          "quantity": 2,
          "unit": "lb"
        }
      ]
    }
  ],
  "warnings": [
    {
      "ingredient": "parmesan cheese",
      "personName": "Child B",
      "note": "Contains dairy (parmesan cheese), and Child B usually skips this"
    }
  ]
}

CSV

Name,Quantity,Unit,Aisle,Category,Recipes,Checked
"chicken breast","2","lb","Meat","meat","Grilled Chicken Salad",""
"pasta","1","lb","Grains","grains","Vegetarian Pasta Primavera",""
"cherry tomatoes","2","cup","Produce","produce","Grilled Chicken Salad",""

Text

Shopping List
=============

Week Starting: 2026-10-12
Generated: Oct 12, 2026, 4:00 PM CDT

Grains:

- [ ] 1 lb pasta
  Used in: Vegetarian Pasta Primavera

Meat:

- [ ] 2 lbs chicken breast
  Used in: Grilled Chicken Salad

Produce:

- [ ] 2 cups cherry tomatoes
  Used in: Grilled Chicken Salad

WARNINGS:
⚠️  Child B: parmesan cheese - Contains dairy (parmesan cheese), and Child B usually skips this

Example Call

{
  "planId": "2d8f1a6b-5c4e-4a91-9c0e-7c2a1e8f4b3d",
  "format": "markdown",
  "groupBy": "recipe",
  "includeStaples": false,
  "includeRuleWarnings": true
}

Example Result

{
  "format": "markdown",
  "list": {
    "mealPlanId": "2d8f1a6b-5c4e-4a91-9c0e-7c2a1e8f4b3d",
    "ingredients": [],
    "itemCount": 15
  },
  "content": "# Shopping List\n\n## Grilled Chicken Salad\n\n- 2 lbs chicken breast...",
  "itemCount": 15,
  "warnings": [
    {
      "ingredient": "parmesan cheese",
      "personName": "Child B",
      "note": "Contains dairy (parmesan cheese), and Child B usually skips this"
    }
  ]
}

Grouping Strategies

aisle

Groups by grocery store aisle (produce, dairy, meat, etc.)
Best for efficient shopping
Kitchen staples land in a Kitchen staples section when includeStaples is true. That is not the pantry food-taxonomy category (flour, canned goods).

recipe

Groups by recipe
Helps with recipe-by-recipe shopping
Good for meal kit-style shopping

Usage Notes

Automatic aggregation: Duplicate ingredients across recipes are combined when possible
Unit conversion: Common unit conversions are applied (e.g., 3 tsp = 1 tbsp). Amounts follow the week cook-for; per-night servings do not change list amounts.
Safety warnings: Inline warnings alert shoppers to dietary restrictions and allergens
Kitchen staples: Enable includeStaples: true to include salt and oil. includePantryItems is still accepted as an alias. On each item, isStaple is canonical; isPantryItem is the same alias.
Check-offs and extras: Markdown uses - [x] for checked keys from the saved trip. Extras such as paper towels appear in list and in markdown/text/csv.
Generated time: The human-readable Generated line uses timeZone (IANA) and always includes a zone label such as CDT or UTC. generatedAt stays ISO-8601 UTC.

get_meal_plan - Get the plan details
check_meal_plan - Verify safety before shopping
save_meal_plan - Save plan before export

export_shopping_list

On this page