Catawiki MCP Server

A Model Context Protocol (MCP) server that gives AI assistants read-only access to Catawiki auction marketplace data — search lots, inspect items, browse categories, and explore auctions. Since Catawiki offers no public API, this server reads publicly available data directly from the website.

Highlights

• 🔍 10 tools — search, lot details, categories, auctions, sellers, images, and more

• 📦 3 resources + 5 prompts for richer, guided AI workflows

• 🛡️ Production-hardened — structured-data parsing, anti-bot detection, rate limiting, caching, and fail-loud error handling

Table of Contents

• Features

• Installation

• Usage

• Architecture

• Reliability & Production Hardening

• Legal Notice

• License

Related MCP server: Simplicate MCP Server

Features

Tools (10)

Resources (3)

Prompts (5)

Installation

# Clone and install
cd catawiki
npm install
npm run build

Usage

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "catawiki": {
      "command": "node",
      "args": ["/absolute/path/to/catawiki/build/index.js"]
    }
  }
}

With MCP Inspector (for debugging)

npm run inspect

Development

npm run dev          # Run with tsx (hot reload)
npm run build        # Compile TypeScript
npm test             # Run test suite
npm run test:watch   # Run tests in watch mode

Architecture

catawiki/
├── src/
│   ├── index.ts                # Entry point (stdio transport)
│   ├── server.ts               # Server assembly
│   ├── tools/
│   │   └── index.ts            # 10 MCP tool definitions
│   ├── resources/
│   │   └── index.ts            # 3 MCP resource definitions
│   ├── prompts/
│   │   └── index.ts            # 5 MCP prompt templates
│   └── services/
│       ├── http-client.ts      # HTTP client with rate limiting & caching
│       └── catawiki-scraper.ts # HTML parser for Catawiki pages
├── tests/
│   ├── http-client.test.ts     # HTTP client unit tests
│   ├── catawiki-scraper.test.ts# Scraper unit tests
│   └── mcp-server.test.ts      # MCP protocol integration tests
├── package.json
├── tsconfig.json
└── vitest.config.ts

Reliability & Production Hardening

This server scrapes a live site, so it is built to fail loudly and correctly rather than silently return wrong data:

• Structured-data first: lot, search, category, seller, and auction data are read from the page's __NEXT_DATA__ hydration payload (what the site actually renders from) — not from brittle CSS classes or JSON-LD.

• Fail-loud on structure change: if a page loads but the expected hydration data is gone (e.g. Catawiki ships a markup change or migrates frameworks), the affected tool returns a clear error asking for a scraper update — it does not return an item with every field N/A. A live regression test guards this.

• Anti-bot detection: a 200 OK is not trusted blindly — Cloudflare / DataDome / PerimeterX challenge pages are detected and surfaced as an access error instead of being parsed as empty content.

• Rate limiting: 10 requests/minute (sliding window) to respect Catawiki.

• Caching: 5-minute default TTL (30 min for categories), with a hard cap on cache size and oldest-entry eviction to bound memory in long-running processes.

• Retries: exponential backoff on transient errors; honors Retry-After on 429.

• Errors: 404 / 403 / 429 / network failures map to actionable, sanitized messages (isError: true) that an agent can act on — no stack traces or internal details leak.

• MCP tool annotations: all tools are marked readOnlyHint + openWorldHint.

Known limitations

• Live bids on list views: search/category results don't carry a live bid in the page HTML (it's pushed over a realtime channel). Pass enrich_bids: true to fill bids for the top 5 results, or call get_lot_details for a single lot.

• get_featured_lots / get_upcoming_auctions: the homepage no longer server-renders this data (it's loaded client-side), so these tools return a message pointing you to search_lots / get_category_lots instead.

Legal Notice

This server scrapes publicly available data from Catawiki's website. It is intended for personal/research use. Please review Catawiki's Terms of Service before using this server. Be mindful of rate limits and respect the website's robots.txt directives.

License

MIT