Superstore MCP Server

An MCP server for Real Canadian Superstore that extracts orders and product data with authentication.

Features

• Order Management: Full order history with item details, dates, prices, images
• DirectAuth: Fast bearer token authentication (no browser needed)
• Data Export: Export orders to CSV or JSON for analysis
• Product Discovery: Browse categories and search products
• Web Content: Fetch and parse web pages

Installation

Quick Install to Cursor

Note: Make sure Cursor is running before clicking the install button.

Manual Installation

# Run directly with npx
npx -y superstore-mcp@latest

# Or clone from GitHub
git clone https://github.com/ai-protocols/superstore-mcp.git
cd superstore-mcp
npm install
npm run build

Configuration

Add to your mcp.json:

{
  "superstore-mcp": {
    "command": "npx",
    "args": ["-y", "superstore-mcp@latest"],
    "env": {
      "SUPERSTORE_BEARER_TOKEN": "your-token-here"
    }
  }
}

Getting Your Bearer Token

1. Log in to https://www.realcanadiansuperstore.ca
2. Open DevTools (F12) → Application → Cookies → www.realcanadiansuperstore.ca
3. Find AccessToken cookie and copy its value (starts with eyJ)
4. Paste into SUPERSTORE_BEARER_TOKEN

Tokens expire after ~1 hour. Refresh by copying a new token from your browser.

Available Tools

Authentication

login - Authenticate session

{}

logout - End session

{}

check_auth_status - Check authentication state

{}

Orders

get_orders - Get order history

{
  "limit": 10,
  "offset": 0
}

get_order_details - Get full order with items

{
  "order_id": "531900014110869"
}

get_recent_orders - Filter orders by date

{
  "days": 90
}

export_orders_csv - Export to CSV

{
  "include_items": true,
  "filepath": "./orders.csv"
}

export_orders_json - Export to JSON

{
  "include_items": true,
  "filepath": "./orders.json"
}

Products

get_categories - Get all categories

{}

get_products - Get products from categories

{
  "category_ids": ["28251"],
  "max_pages_per_category": 1
}

get_category - Get single category

{
  "category_id": "28251"
}

get_product - Search for product

{
  "category_id": "28251",
  "product_name": "bread"
}

search_products - Search products (alias)

{
  "category_id": "28251",
  "product_name": "milk"
}

get_product_details - Get product details from URL

{
  "product_url": "https://www.realcanadiansuperstore.ca/..."
}

get_product_details_by_name - Search and get details

{
  "category_id": "28251",
  "product_name": "butter"
}

Web Utilities

fetch_txt - Fetch web page as text

{
  "url": "https://www.realcanadiansuperstore.ca"
}

parse_sitemap - Parse sitemap

{
  "sitemap_url": "https://www.realcanadiansuperstore.ca/sitemap_index.xml"
}

Example Usage

Export All Orders

// Login
await mcp.call("login", {});

// Export with full item details
await mcp.call("export_orders_csv", {
  "include_items": true,
});

Analyze Spending

// Get recent orders
const orders = await mcp.call("get_recent_orders", { "days": 90 });

// Get details for each
for (const order of orders.orders) {
  const details = await mcp.call("get_order_details", {
    "order_id": order.id,
  });
  console.log(`${order.id}: ${details.items.length} items`);
}

Architecture

• DirectAuth: Uses bearer token from browser (recommended)
• API Integration: Calls api.pcexpress.ca/pcx-bff with proper headers
• Fallback Mode: Puppeteer browser automation if no bearer token provided
• HTML Parsing: JSDOM for product pages

Documentation

• API Reference
• Authentication Guide
• Security Guide

License

MIT

Disclaimer

Unofficial tool. Not affiliated with Loblaw Companies or Real Canadian Superstore. Use responsibly.

---

Repository: https://github.com/ai-protocols/superstore-mcp
Version: 2.0.0