npm package: @striderlabs/mcp-costco
Description: MCP server connector for Costco warehouse shopping — search products, manage cart, check availability, schedule pickup, and track orders
Author: Strider Labs
Latest version: 0.1.0

# @striderlabs/mcp-costco

MCP server connector for Costco warehouse shopping — search products, manage cart, check warehouse availability, schedule pickup, track orders, and view membership details via browser automation.

## Overview

This package provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that enables AI agents to interact with Costco.com through Playwright browser automation with stealth features to avoid bot detection.

## Installation

```bash
npx @striderlabs/mcp-costco
```

Or install globally:

```bash
npm install -g @striderlabs/mcp-costco
mcp-costco
```

## MCP Configuration

Add to your MCP client configuration:

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

## Tools

### `status`
Check Costco authentication status and session info.

**No parameters required.**

---

### `login`
Authenticate with your Costco account using email and password via browser automation.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | Yes | Costco account email |
| `password` | string | Yes | Costco account password |
| `headless` | boolean | No | Run browser headless (default: `true`). Set `false` to see the browser window. |

---

### `logout`
Clear Costco session and stored cookies.

**No parameters required.**

---

### `search_products`
Search Costco products by keyword with optional filters.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search term |
| `min_price` | number | No | Minimum price filter |
| `max_price` | number | No | Maximum price filter |
| `sort_by` | string | No | Sort order: `relevance`, `price_low`, `price_high`, `top_rated`, `best_seller` |
| `limit` | number | No | Max results (default: `10`, max: `24`) |

---

### `get_product`
Get detailed product information including price, description, and availability.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | No* | Full Costco product URL |
| `item_number` | string | No* | Costco product item number |

*At least one of `url` or `item_number` is required.

---

### `check_availability`
Check warehouse and online availability for a product.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | No* | Costco product URL |
| `item_number` | string | No* | Costco product item number |
| `warehouse_zip` | string | No | ZIP code to check nearest warehouse stock |

*At least one of `url` or `item_number` is required.

---

### `add_to_cart`
Add a product to the Costco cart.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | No* | Costco product URL |
| `item_number` | string | No* | Costco product item number |
| `quantity` | number | No | Quantity to add (default: `1`) |

*At least one of `url` or `item_number` is required.

---

### `view_cart`
View current Costco cart contents and totals.

**No parameters required.**

---

### `checkout`
Preview checkout summary for the Costco cart. Returns order details without placing the order.

**No parameters required.**

> Note: This tool intentionally does **not** place the order. It returns the order summary (items, subtotal, shipping, tax, total) so you can review before proceeding manually.

---

### `get_orders`
Get Costco order history.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | number | No | Number of recent orders to return (default: `10`) |

---

### `schedule_pickup`
Schedule same-day or future warehouse pickup. Finds the nearest warehouse to a ZIP code and confirms pickup availability.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `warehouse_zip` | string | Yes | ZIP code to find nearest pickup warehouse |
| `date` | string | No | Preferred pickup date: `"today"`, `"tomorrow"`, or `"YYYY-MM-DD"` |
| `time_slot` | string | No | Preferred time: `"morning"`, `"afternoon"`, `"evening"` |

---

### `get_membership`
Get Costco membership details including type, member number, and expiration date.

**No parameters required.** (Requires login)

Returns:
- Member name and number
- Membership type (Gold Star, Executive, Business)
- Expiration / renewal date
- Executive reward info (if applicable)
- Home warehouse

---

## Session Persistence

Cookies and auth info are stored in `~/.striderlabs/costco/` and persist across sessions. Once logged in, subsequent tool calls reuse the existing session without re-authenticating.

## Technical Details

- **Transport**: stdio (standard MCP transport)
- **Browser**: Chromium via Playwright with stealth patches
- **Bot detection bypass**: Removes webdriver flag, spoofs plugins/languages, patches permissions API
- **Session storage**: `~/.striderlabs/costco/cookies.json`, `~/.striderlabs/costco/auth.json`

## Requirements

- Node.js >= 18.0.0
- Chromium (installed automatically with Playwright)

## License

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