# recipe-shoplist-mcp

Turns a meal idea into a categorized shopping list with one-click search links — no accounts, no API keys.

An MCP (Model Context Protocol) server that takes a natural language meal request, generates a structured recipe, consolidates ingredients into a categorized shopping list, and optionally generates pre-filled search URLs for common grocery stores.

## Features

- **Recipe Generation** — Describe what you want ("something quick with chicken and rice", "vegan pasta for 4") and get a structured recipe with ingredients, steps, and timing
- **Shopping List Builder** — Consolidates duplicate ingredients across multiple recipes (two recipes need garlic? → combined quantity)
- **Grocery Category Grouping** — Items sorted by store section: produce, dairy, meat, pantry, spices, etc.
- **Export Formats** — Plain text, Markdown, or clickable search links for Amazon Fresh, Walmart, or generic Google Shopping
- **Save to File** — Export your shopping list as a `.md` or `.txt` file to open, print, or share
- **Vague Ingredient Flagging** — Flags entries like "some spices" so you know to clarify
- **Multi-Recipe Merging** — Plan a week of meals and get one combined shopping list

## Installation

```bash
git clone https://github.com/Sara-Eltayeb/recipe-shoplist-mcp.git
cd recipe-shoplist-mcp
npm install
npm run build
```

## Register in Your MCP Client

Add to your MCP client configuration (e.g. Claude Desktop, opencode, etc.):

```json
{
  "mcpServers": {
    "recipe-shoplist": {
      "command": "node",
      "args": ["/absolute/path/to/recipe-shoplist-mcp/dist/index.js"]
    }
  }
}
```

Or if installed globally via npm:

```json
{
  "mcpServers": {
    "recipe-shoplist": {
      "command": "recipe-shoplist-mcp"
    }
  }
}
```

## Tools

### `generate_recipe`
Generate a structured recipe from a natural language request.

| Parameter | Type | Description |
|-----------|------|-------------|
| `request` | string | Natural language meal request |
| `servings` | number? | Number of servings (default: 4) |
| `dietary_restrictions` | string[]? | e.g. `["vegan", "gluten-free"]` |

### `build_shopping_list`
Consolidate ingredients from one or more recipes into a categorized shopping list.

| Parameter | Type | Description |
|-----------|------|-------------|
| `ingredients` | Ingredient[] | Array of `{name, quantity, unit}` |
| `recipe_names` | string[]? | Names of source recipes |

### `export_list`
Export the latest shopping list in your preferred format.

| Parameter | Type | Description |
|-----------|------|-------------|
| `format` | `"text" \| "markdown" \| "url_links"` | Output format |
| `store` | `"amazon_fresh" \| "walmart" \| "generic"`? | Store for URL links |

### `save_list_to_file`
Save the shopping list to a local `.md` or `.txt` file.

| Parameter | Type | Description |
|-----------|------|-------------|
| `filename` | string? | Filename without extension |
| `format` | `"text" \| "markdown"`? | File format (default: markdown) |

## Example Prompts

- *"Plan 3 dinners for this week and give me one combined shopping list"*
- *"Make a shopping list for a vegan pasta night and give me Walmart search links"*
- *"I want something quick with chicken and rice, then save the list to a file"*
- *"Give me 2 meal ideas for the week and combine everything into one markdown shopping list"*

## Limitations

- **No cart automation** — Search links open a search or product page on the retailer's site. Adding items to a cart and checking out requires retailer partner API access, which is not available without approval.
- **No external API keys** — Recipe generation relies on the calling AI assistant's own creativity. This server structures and validates the output but does not call external recipe APIs.
- **Vague ingredients** — Terms like "some spices" or "seasoning to taste" are flagged for clarification rather than guessed at.

## License

MIT