Catawiki 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

Features

Tools (10)

Tool	Description
search_lots	Search for lots/items with filters (price, sort), pagination, and optional enrich_bids for live bids on the top 5 results
get_lot_details	Get detailed info about a specific lot (title, description, bids, seller, images)
list_categories	List all available auction categories
get_category_lots	Browse lots within a specific category
get_auction_details	Get details of a themed auction and its lots
get_upcoming_auctions	List upcoming/active auctions
get_featured_lots	Get featured/trending lots from the homepage
get_seller_profile	Get seller information and recent lots
get_lot_images	Get all image URLs for a specific lot
scrape_catawiki_page	Scrape any public Catawiki page (help, about, stories, etc.)

Resources (3)

Resource	URI	Description
Platform Info	catawiki://info	General platform information, features, URL patterns
Categories	catawiki://categories	Dynamic list of all auction categories
Server Info	catawiki://server-info	Server version, capabilities, uptime

Prompts (5)

Prompt	Description
analyze-lot	Analyze a lot's value, authenticity, and buying considerations
compare-lots	Side-by-side comparison of multiple lots
explore-category	Discover what's available in a category with price ranges
find-deals	Search for potentially undervalued items
market-overview	Overview of current marketplace activity

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