# @striderlabs/mcp-costco

MCP server connector for Costco — search products, manage cart, check membership, find warehouses, and place orders via browser automation.

## Features

- **Search Products** — Search Costco.com by keyword, category, or brand with price filters
- **Product Details** — Get full product info, price, availability, and item number
- **Cart Management** — Add items, view cart, update quantities, remove items
- **Delivery Options** — Check home delivery and warehouse pickup availability
- **Checkout** — Preview and place orders (with confirmation step)
- **Order History** — View past orders with status
- **Order Tracking** — Track shipment status and estimated delivery
- **Membership** — Check membership type, number, and renewal date
- **Warehouse Locations** — Find nearby Costco warehouses by ZIP or city
- **Warehouse Stock** — Check in-store availability at specific locations

## Requirements

- Node.js 18+
- A Costco membership account
- Playwright browsers installed

## Installation

```bash
npx playwright install chromium
```

## Usage with Claude Desktop

Add to your `claude_desktop_config.json`:

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

## Tools

### Authentication

| Tool | Description |
|------|-------------|
| `status` | Check authentication status and session info |
| `login` | Authenticate with email and password |
| `logout` | Clear session and stored cookies |

### Shopping

| Tool | Description |
|------|-------------|
| `search_products` | Search by name, category, or brand |
| `get_product_details` | Get full product info, price, availability |
| `add_to_cart` | Add item to cart by URL or item number |
| `view_cart` | View cart contents and totals |
| `update_cart` | Change quantities or remove items (qty=0 removes) |

### Delivery & Checkout

| Tool | Description |
|------|-------------|
| `get_delivery_options` | Check delivery/pickup availability for a ZIP |
| `select_delivery` | Choose home delivery or warehouse pickup |
| `checkout` | Preview (confirm=false) or place order (confirm=true) |

### Orders

| Tool | Description |
|------|-------------|
| `get_orders` | View order history |
| `track_order` | Track delivery status by order number |

### Membership & Locations

| Tool | Description |
|------|-------------|
| `get_membership` | Check membership type, number, and renewal date |
| `get_warehouse_locations` | Find nearby warehouses by ZIP or city |
| `check_warehouse_stock` | Check in-warehouse availability |

## Example Usage

```
# Login
login(email="you@example.com", password="yourpassword")

# Search for items
search_products(query="kirkland olive oil", limit=5)

# Get product details
get_product_details(item_number="1234567")

# Add to cart
add_to_cart(item_number="1234567", quantity=2)

# Preview checkout
checkout(confirm=false)

# Place order
checkout(confirm=true)

# Check membership
get_membership()

# Find nearby warehouses
get_warehouse_locations(zip_code="94105", limit=3)
```

## Environment Variables

Credentials can also be passed via environment variables (used as defaults if login tool is not called):

| Variable | Description |
|----------|-------------|
| `COSTCO_EMAIL` | Costco account email |
| `COSTCO_PASSWORD` | Costco account password |

## Session Persistence

Sessions are stored in `~/.striderlabs/costco/` and persist across runs. You only need to log in once per machine.

## Headless Mode

By default, the browser runs headless. To debug, pass `headless=false` to the `login` tool to see the browser window.

## Author

[Strider Labs](https://striderlabs.ai) — Building AI agent infrastructure.

## License

MIT