Skip to main content
Glama
hung-ngm

coles-woolworths

by hung-ngm
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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: Katzilla 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.
ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
store_idNo0584
limitNo

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a search operation but doesn't describe what happens when no results are found, whether results are paginated, what authentication might be required, rate limits, or what the return format looks like. For a search tool with zero annotation coverage, this leaves significant behavioral questions unanswered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and well-structured with a clear purpose statement followed by parameter explanations. The bullet-point format for parameters is efficient. However, the first sentence could be more specific (e.g., 'Search for grocery products at Coles supermarkets'), and the parameter descriptions could be slightly more informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a search tool with 3 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what the tool returns (product names, prices, availability?), error conditions, authentication requirements, or how results are ordered. The sibling tool context isn't leveraged to provide comparative guidance, leaving significant gaps for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description lists all three parameters with brief explanations, but the input schema has 0% description coverage. The description adds basic semantic meaning (e.g., 'The product search query' for 'query'), but doesn't provide format details, constraints, or examples. It compensates somewhat for the schema's lack of descriptions but doesn't fully address the coverage gap, earning a baseline score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as 'Search for products at Coles' - a specific verb ('Search') and resource ('products at Coles'). It distinguishes from the sibling tool 'get_woolworths_products' by specifying the retailer. However, it doesn't explicitly mention what type of search this is (e.g., text-based product search vs. category browsing), which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. While the sibling tool name suggests a different retailer (Woolworths), the description doesn't mention this alternative or provide any context about when to choose Coles over Woolworths. There's no information about prerequisites, constraints, or typical use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_woolworths_productsC

Search for products at Woolworths.

Args:
    query: The product search query.
    limit: Maximum number of products to return.
ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
limitNo

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions searching but doesn't describe what the search returns (e.g., product details, pricing, availability), whether it requires authentication, rate limits, or error conditions. This leaves significant gaps in understanding the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized with a clear purpose statement followed by parameter details. It's front-loaded with the main function and uses a structured format for parameters, though the 'Args' section could be integrated more smoothly into the narrative flow.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a product search tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the return values look like (e.g., product list format), error handling, or contextual constraints like availability by region, making it inadequate for full understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description includes an 'Args' section that lists and briefly describes both parameters ('query' and 'limit'), adding meaning beyond the input schema which has 0% description coverage. However, it doesn't provide details like query syntax examples, limit constraints, or default behavior, leaving some semantic gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Search') and resource ('products at Woolworths'), making it immediately understandable. However, it doesn't explicitly differentiate from its sibling tool 'get_coles_products' beyond the brand name, which is implied but not stated as a distinguishing factor.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. There's no mention of the sibling tool 'get_coles_products' or any context about when Woolworths-specific searches are appropriate versus other product search options.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updates
    • First observedget_coles_products
    • First observedget_woolworths_products
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.1/5.0
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
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/hung-ngm/coles-woolworths-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server