# PriceAtlas MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that exposes the PriceAtlas food price tracking API as tools for AI assistants.

Query global food prices, search products by barcode or name, compare costs across 27 countries, and trigger real-time price scraping — all from Claude, Cursor, Windsurf, or any MCP-compatible client.

## Tools

| Tool | Description |
|------|-------------|
| `lookup_product` | Look up a product by barcode (EAN/UPC) via Open Food Facts |
| `search_products` | Search products by name |
| `get_prices` | Get price observations and min/avg stats, optionally filtered by country |
| `submit_price` | Submit a price observation for a product at a store |
| `get_world_prices` | Get aggregated global prices from Open Food Facts |
| `list_stores` | List available stores (68 across 27 countries) |
| `list_countries` | List all 27 supported countries with currencies |
| `run_connectors` | Scrape fresh prices from 6 sources (OFF, Kroger, Walmart, REWE, Migros, A101) |

## Prerequisites

The PriceAtlas API must be running. This MCP server is a thin wrapper that calls the API over HTTP.

```bash
# Clone and run PriceAtlas API (private repo)
cd PriceAtlas
pnpm install
pnpm db:migrate
pnpm db:seed
pnpm dev  # starts API on port 4000
```

## Install

```bash
git clone https://github.com/musaceylan/priceatlas-mcp.git
cd priceatlas-mcp
npm install
npm run build
```

## Usage with Claude Desktop

Add to your Claude Desktop config file:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "priceatlas": {
      "command": "node",
      "args": ["/absolute/path/to/priceatlas-mcp/dist/index.js"],
      "env": {
        "PRICEATLAS_API_URL": "http://localhost:4000"
      }
    }
  }
}
```

Restart Claude Desktop. You'll see PriceAtlas tools available in the tools menu (hammer icon).

## Usage with Claude Code (CLI)

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "priceatlas": {
      "command": "node",
      "args": ["/absolute/path/to/priceatlas-mcp/dist/index.js"],
      "env": {
        "PRICEATLAS_API_URL": "http://localhost:4000"
      }
    }
  }
}
```

Restart Claude Code to pick up the new server.

## Usage with Cursor

Open **Settings > MCP Servers > Add Server** and configure:

```json
{
  "priceatlas": {
    "command": "node",
    "args": ["/absolute/path/to/priceatlas-mcp/dist/index.js"],
    "env": {
      "PRICEATLAS_API_URL": "http://localhost:4000"
    }
  }
}
```

## Usage with Windsurf

Add to your Windsurf MCP config (`~/.windsurf/mcp.json`):

```json
{
  "mcpServers": {
    "priceatlas": {
      "command": "node",
      "args": ["/absolute/path/to/priceatlas-mcp/dist/index.js"],
      "env": {
        "PRICEATLAS_API_URL": "http://localhost:4000"
      }
    }
  }
}
```

## Configuration

| Env Variable | Default | Description |
|-------------|---------|-------------|
| `PRICEATLAS_API_URL` | `http://localhost:4000` | Base URL of the PriceAtlas API |

## Example Prompts

Once connected, you can ask your AI assistant:

- "Look up barcode 8690637050602"
- "What's the cheapest milk in Germany?"
- "Compare Nutella prices between Turkey and the US"
- "Search for 'olive oil' and get prices for the first result"
- "Run all connectors for barcode 4005808262151 in DE"
- "List all stores in Turkey"
- "Which countries have the cheapest pasta?"

## Data Sources

The server aggregates data from:

- **Open Food Facts** — Global product database + crowdsourced prices
- **Kroger** — US grocery chain (requires API keys)
- **Walmart** — US retail (requires API key)
- **REWE** — German supermarket
- **Migros** — Turkish supermarket
- **A101** — Turkish discount store

## Architecture

```
Claude / Cursor / Any MCP Client
        |
        | stdio (JSON-RPC)
        v
  PriceAtlas MCP Server
        |
        | HTTP (fetch)
        v
  PriceAtlas Fastify API (:4000)
        |
        v
  PostgreSQL + Open Food Facts + 6 Connectors
```

## License

MIT