# itad-mcp

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that gives AI assistants access to [IsThereAnyDeal (ITAD)](https://isthereanydeal.com) game prices, discounts, all-time historical lows, and active store sales via official structured [IsThereAnyDeal API v3/v1](https://github.com/isthereanydeal/api) endpoints.

Query pricing across major digital storefronts (Steam, GOG, Epic Games Store, Humble, Fanatical, GreenManGaming, and more) with batching support and zero payload bloat. For underlying API specifications and rate limits, see the official [IsThereAnyDeal API Documentation](https://github.com/isthereanydeal/api).

---

## Tools

| Tool | Parameters | Description |
|------|------------|-------------|
| `search_games` | `query` (string) | Search ITAD by game title query — returns matching games with ITAD UUIDs. |
| `lookup_game` | `steamAppId?` (number), `title?` (string) | Lookup ITAD game metadata and internal ITAD UUID using a Steam AppID or game title. |
| `get_game_prices` | `ids` (string \| string[]), `country?` (string) | Get current prices and discounts across digital storefronts for 1 or more ITAD game UUIDs. |
| `get_historical_low` | `ids` (string \| string[]), `country?` (string) | Get all-time historical low prices across digital storefronts for 1 or more ITAD game UUIDs. |
| `get_active_deals` | `minDiscount?` (number), `limit?` (number), `country?` (string) | Get top active game sales across digital storefronts filtered by minimum discount percentage. |

---

## Prerequisites

- [Node.js](https://nodejs.org) v18 or later
- An **IsThereAnyDeal API Key**

### Getting an IsThereAnyDeal API Key

1. Go to [isthereanydeal.com/apps](https://isthereanydeal.com/apps/)
2. Log in or create a free account
3. Register your app to generate an API key
4. Copy your API Key to use in your MCP configuration

---

## Installation & Configuration

### Option A — npx (Recommended)

Add the following to your MCP client config file:

```json
{
  "mcpServers": {
    "itad": {
      "command": "npx",
      "args": ["-y", "itad-mcp"],
      "env": {
        "ITAD_API_KEY": "your_itad_api_key_here"
      }
    }
  }
}
```

### Option B — Clone and build locally

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

Then add to your MCP config:

```json
{
  "mcpServers": {
    "itad": {
      "command": "node",
      "args": ["/path/to/itad-mcp/dist/index.js"],
      "env": {
        "ITAD_API_KEY": "your_itad_api_key_here"
      }
    }
  }
}
```

---

## MCP Client Config Locations

| Client | Config File Location |
|--------|----------------------|
| **Antigravity / AGY** | `~/.gemini/antigravity-cli/settings.json` or `mcp_config.json` |
| **Claude Desktop (macOS)** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Claude Desktop (Windows)** | `%APPDATA%\Claude\claude_desktop_config.json` |

---

## Example Usage

Once connected, you can ask your AI assistant questions like:

- *"Check if Elden Ring is currently on sale across any store"*
- *"What is the all-time historical low price for Cyberpunk 2077?"*
- *"Show me top active PC game deals with at least 60% off"*
- *"Find current prices for all unplayed games in my Steam library"*

---

## Performance & Security

| Feature | Details |
|---------|---------|
| **Batching Support** | Query prices & historical lows for up to 50 games in a single API call. |
| **In-Memory Cache** | 30-minute TTL in-memory caching layer protects against rate limits. |
| **Zero Secrets Policy** | API keys are passed strictly via environment variables at runtime. |

---

## License

MIT