tesco-grocery-mcp

An MCP server that wraps Tesco's grocery APIs, letting AI assistants like Claude search products, manage your basket, and book delivery slots.

Tools

Authentication

| Tool | Description | |------|-------------| | set_auth_token | Set bearer token and customer UUID from your browser session |

Search & Browse

| Tool | Description | |------|-------------| | search_products | Search for grocery products (supports batched multi-query) | | get_product_details | Get detailed info for a specific product | | get_offers | Find products on promotion or Clubcard price | | get_substitutions | Find alternatives for unavailable products | | browse_categories | Get the department/aisle/shelf taxonomy tree | | get_favourites | Get your favourite products | | get_order_history | Get previous orders |

Basket

| Tool | Description | |------|-------------| | get_basket | View current basket contents | | add_to_basket | Add products or change quantities | | remove_from_basket | Remove products from basket |

Delivery Slots

| Tool | Description | |------|-------------| | get_delivery_slots | View available delivery slots for a date range | | get_available_weeks | See which weeks have delivery slots | | get_current_slot | Check if you have a slot booked | | book_delivery_slot | Book or unbook a delivery slot |

Prerequisites

• Node.js >= 18
• A Tesco.com account with an active grocery session

Installation

Via npx (recommended)

No installation needed — just configure your MCP client (see below).

Global install

npm install -g tesco-grocery-mcp

From source

git clone https://github.com/GavinAttard/tesco-grocery-mcp.git
cd tesco-grocery-mcp
npm install
npm run build

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "tesco-grocery": {
      "command": "npx",
      "args": ["-y", "tesco-grocery-mcp"]
    }
  }
}

Claude Code

claude mcp add tesco-grocery -- npx -y tesco-grocery-mcp

Other MCP clients

Run the server on stdio:

npx -y tesco-grocery-mcp

Or if installed globally:

tesco-grocery

Authentication

The server requires a bearer token from an active Tesco.com session:

1. Log in to tesco.com/groceries in your browser
2. Open DevTools (F12) → Network tab
3. Find any request to xapi.tesco.com and copy the Authorization header value and x-customer-uuid header value
4. Use the set_auth_token tool to provide these credentials

Credentials are persisted locally so you only need to do this when your session expires.

See .env.example for the credential format.

Shopping Skill

The skills/SKILL.md file contains an optimised execution guide that teaches AI assistants how to efficiently handle a full weekly grocery shop — from searching to basket management to delivery slot booking. You can use it as a system prompt or reference for your own workflows.

License

MIT