Coles and Woolworths MCP Server

Servidor MCP da Coles e Woolworths

Uma implementação experimental de servidor Model Context Protocol (MCP) que permite que assistentes de IA pesquisem informações de produtos dos principais supermercados da Austrália: Coles e Woolworths. Este servidor expõe funcionalidade de busca de produtos através do protocolo MCP, facilitando que assistentes de IA recuperem preços e detalhes de produtos.

Demonstração

Uso com Claude Desktop

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

Recursos

• Busca de Produtos: Pesquise produtos nos supermercados Coles e Woolworths
• Comparação de Preços: Obtenha informações de preços de ambos os varejistas em um formato consistente
• Seleção de Loja: Pesquise em lojas específicas da Coles usando IDs de loja
• Limitação de Resultados: Controle quantos produtos são retornados nos resultados da busca

Início Rápido para Claude Desktop, Cursor e outros clientes

1. Clone este repositório

git clone https://github.com/hung-ngm/coles-woolworths-mcp-server.git

2. Navegue até o diretório do projeto

cd coles-woolies-mcp

3. Instale os pré-requisitos

4. Configure seu cliente MCP para usar este servidor (veja Integração com Clientes MCP)

Instalação

Pré-requisitos

1. Python 3.8 ou superior
2. O gerenciador de pacotes uv

Instalando uv

uv é um instalador e resolvedor de pacotes Python rápido. Para instalar:

macOS/Linux:

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

Windows:

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

Configuração

1. Clone o repositório e navegue até o diretório do projeto
2. Use uv para instalar as dependências:

# Install dependencies
uv pip install fastmcp requests python-dotenv

Configuração

O servidor usa as seguintes variáveis de ambiente:

• COLES_API_KEY: chave de API para acessar a API da Coles (necessária para buscas de produtos da Coles)

Você pode definir essas variáveis em um arquivo .env no diretório do projeto.

Executando o Servidor

Para executar o servidor MCP da Coles e Woolworths diretamente usando uv:

uv run main.py

Por padrão, o servidor executa com transporte stdio para integração com clientes MCP.

Integração com Clientes MCP

Configuração do Claude Desktop

Para usar o servidor MCP da Coles e Woolworths com o Claude Desktop:

1. Localize seu arquivo de configuração do Claude Desktop (geralmente claude_desktop_config.json)
2. Adicione a seguinte configuração à seção mcpServers:

{
  "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"
      ]
    }
  }
}

Substitua /full/path/to/coles-woolies-mcp/main.py pelo caminho absoluto para o seu arquivo main.py.

3. Reinicie o Claude Desktop para que as alterações tenham efeito

Configuração do Cursor IDE

Para integrar com o Cursor IDE:

1. Abra seu arquivo de configuração do Cursor
2. Adicione o seguinte à seção mcpServers:

{
  "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"
      ]
    }
  }
}

Ferramentas Disponíveis

O servidor MCP da Coles e Woolworths expõe as seguintes ferramentas:

• get_coles_products: Pesquise produtos nos supermercados Coles com seleção opcional de loja
• get_woolworths_products: Pesquise produtos nos supermercados Woolworths

Exemplo de Uso no Claude

Você pode usar as ferramentas no Claude assim:

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

O Claude então usará as ferramentas apropriadas para pesquisar os produtos e retornar os resultados.

Requisitos

• Python 3.8 ou superior
• Pacote fastmcp
• Pacote requests
• Pacote python-dotenv
• Cliente compatível com MCP (Claude Desktop, Cursor, etc.)