npm package: @striderlabs/mcp-freshdirect
Description: MCP server for FreshDirect - let AI agents search products, manage cart, and place grocery orders
Author: Strider Labs
Latest version: 0.1.0

# @striderlabs/mcp-freshdirect

[![npm](https://img.shields.io/npm/v/@striderlabs/mcp-freshdirect)](https://www.npmjs.com/package/@striderlabs/mcp-freshdirect)
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

MCP server that gives AI agents the ability to search products, manage a cart, and place grocery orders on [FreshDirect](https://www.freshdirect.com) — the Northeast US grocery delivery service.

Built by [Strider Labs](https://striderlabs.ai) — building the action layer for AI agents.

## Features

- **Search Products** — Find groceries across FreshDirect with prices and availability
- **Department Browsing** — List all departments and categories
- **Product Details** — Get full product info including nutrition and description
- **Cart Management** — Add items and view cart contents
- **Delivery Slots** — View available delivery windows and pricing
- **Checkout** — Preview and place orders with delivery time selection
- **Order Tracking** — Check order status by order ID
- **Session Persistence** — Cookies saved locally for seamless re-authentication

## Installation

```bash
npm install @striderlabs/mcp-freshdirect
# or globally
npm install -g @striderlabs/mcp-freshdirect
```

### Prerequisites

```bash
npx playwright install chromium
```

## MCP Client Configuration (Claude Desktop)

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "freshdirect": {
      "command": "npx",
      "args": ["@striderlabs/mcp-freshdirect"]
    }
  }
}
```

## Available Tools

### Products & Browsing

| Tool | Description |
|------|-------------|
| `search_items` | Search for products by keyword |
| `get_product_details` | Get full details for a specific product |
| `get_departments` | List all departments/categories |

### Cart

| Tool | Description |
|------|-------------|
| `add_to_cart` | Add a product to the cart (by ID or URL) |
| `view_cart` | View current cart contents and totals |

### Orders & Delivery

| Tool | Description |
|------|-------------|
| `get_delivery_slots` | Get available delivery time windows |
| `checkout` | Preview or place an order |
| `get_order_status` | Check order status by order ID |

## Tool Details

### `search_items`
```json
{
  "query": "organic whole milk",
  "limit": 10
}
```

### `get_product_details`
```json
{
  "product_id": "FDM_ORGMILK64"
}
```
Or pass the full product URL from a `search_items` result.

### `add_to_cart`
```json
{
  "product_id": "FDM_ORGMILK64",
  "quantity": 2
}
```

### `checkout`
```json
{
  "delivery_slot": "Tue Mar 18 3pm-5pm",
  "confirm": false
}
```
Without `confirm: true`, returns a preview. **Always show the preview to the user and get explicit confirmation before setting `confirm: true`.**

### `get_order_status`
```json
{
  "order_id": "FD-12345678"
}
```

## Order Safety

- `checkout` without `confirm: true` → Returns cart preview only, no order placed
- `checkout` with `confirm: true` → Initiates checkout flow
- Agents **must** show the preview and get explicit user confirmation before placing orders

## Authentication

FreshDirect requires an account with a delivery address set up. The connector persists session cookies at `~/.strider/freshdirect/cookies.json`. On first use:

1. Visit [freshdirect.com](https://www.freshdirect.com) in your browser
2. Log in to your account
3. Set your delivery address
4. The connector will use those saved cookies on subsequent runs

## Service Area

FreshDirect delivers to the **New York metropolitan area**, including:
- New York City (all five boroughs)
- New Jersey (select areas)
- Connecticut (select areas)
- Philadelphia metropolitan area
- Washington D.C. metropolitan area

## License

MIT — [Strider Labs](https://striderlabs.ai)