Skip to main content
Glama
coles-woolworths

coles-woolworths

by hung-ngm

Coles and Woolworths MCP Server

An experimental Model Context Protocol (MCP) server implementation that allows AI assistants to search for product information from Australia's major supermarkets: Coles and Woolworths. This server exposes product search functionality through the MCP protocol, making it easy for AI assistants to retrieve product pricing and details.

Demo

Use with Claude Desktop

https://github.com/user-attachments/assets/0af3b07a-578a-4112-acfe-e7a7eee31161

Related MCP server: Bitcoin-MCP

Features

  • Product Search: Search for products at both Coles and Woolworths supermarkets

  • Price Comparison: Get pricing information from both retailers in a consistent format

  • Store Selection: Search specific Coles stores using store IDs

  • Result Limiting: Control how many products are returned in search results

Quick Start for Claude Desktop, Cursor, and other clients

  1. Clone this repository

git clone https://github.com/hung-ngm/coles-woolworths-mcp-server.git
  1. Navigate to the project directory

cd coles-woolies-mcp
  1. Install the prerequisites

  2. Configure your MCP client to use this server (see Integrating with MCP Clients)

Installation

Prerequisites

  1. Python 3.8 or higher

  2. The uv package manager

Installing uv

uv is a fast Python package installer and resolver. To install:

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Setup

  1. Clone the repository and navigate to the project directory

  2. Use uv to install dependencies:

# Install dependencies
uv pip install fastmcp requests python-dotenv

Configuration

The server uses the following environment variables:

  • COLES_API_KEY: API key for accessing the Coles API (required for Coles product searches)

You can set these variables in a .env file in the project directory.

Running the Server

To run the Coles and Woolworths MCP server directly using uv:

uv run main.py

By default, the server runs with stdio transport for MCP client integration.

Integrating with MCP Clients

Claude Desktop Configuration

To use the Coles and Woolworths MCP server with Claude Desktop:

  1. Locate your Claude Desktop configuration file (usually claude_desktop_config.json)

  2. Add the following configuration to the mcpServers section:

{
  "mcpServers": {
    "coles-woolies-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "--with",
        "requests",
        "--with", 
        "python-dotenv",
        "fastmcp",
        "run",
        "/full/path/to/coles-woolies-mcp/main.py"
      ]
    }
  }
}

Replace /full/path/to/coles-woolies-mcp/main.py with the absolute path to your main.py file.

  1. Restart Claude Desktop for the changes to take effect

Cursor IDE Configuration

To integrate with Cursor IDE:

  1. Open your Cursor configuration file

  2. Add the following to the mcpServers section:

{
  "mcpServers": {
    "coles-woolies-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "--with",
        "requests",
        "--with", 
        "python-dotenv",
        "fastmcp",
        "run",
        "/full/path/to/coles-woolies-mcp/main.py"
      ]
    }
  }
}

Available Tools

The Coles and Woolworths MCP server exposes the following tools:

  • get_coles_products: Search for products at Coles supermarkets with optional store selection

  • get_woolworths_products: Search for products at Woolworths supermarkets

Example Usage in Claude

You can use the tools in Claude like this:

Could you check the price of Cadbury chocolate at both Coles and Woolworths?

Claude will then use the appropriate tools to search for the products and return the results.

Requirements

  • Python 3.8 or higher

  • fastmcp package

  • requests package

  • python-dotenv package

  • MCP-compatible client (Claude Desktop, Cursor, etc.)

Available Tools

2 tools
get_coles_productsC

Search for products at Coles.

Args:
    query: The product search query.
    store_id: The Coles store ID to search in.
    limit: Maximum number of products to return.

Inputs: query (required), store_id, limit.

get_woolworths_productsC

Search for products at Woolworths.

Args:
    query: The product search query.
    limit: Maximum number of products to return.

Inputs: query (required), limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct purposes: one searches products at Coles, the other at Woolworths. Their names explicitly differentiate the target retailer, eliminating any ambiguity about which tool to use for each store.

    Naming Consistency5/5

    Both tools follow an identical verb_noun pattern: get_<retailer>_products. This consistent naming convention makes it easy to understand and predict tool functionality across the set.

    Tool Count2/5

    With only two tools, the server feels under-scoped for a grocery shopping assistant. While the tools cover basic product search, there are no tools for cart management, checkout, store location, or price comparison between retailers, making the surface too thin for practical use.

    Completeness2/5

    The toolset is severely incomplete for grocery shopping. It lacks essential operations like adding items to a cart, viewing cart contents, checking out, finding nearby stores, or comparing prices across Coles and Woolworths. Agents will hit dead ends after product searches.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers