Rijksmuseum MCP Server: Search, Artwork Details, Tiles

Overview

The Rijksmuseum MCP Server exposes Rijksmuseum artwork data through a Model Context Protocol (MCP)–compatible HTTP API. It lets developers search the Rijksmuseum collection, retrieve rich artwork metadata, access high-resolution image tiles for zooming viewers, and explore user-specific collections. The server acts as a translator between Rijksmuseum resources and MCP-consumer applications such as galleries, annotation tools, or generative models that need structured visual context.

This server is useful when you need a lightweight, local or hosted service that standardizes calls for search, model (artwork) detail, and tile access without wiring directly to the upstream API. It helps with performance (via caching), consistent JSON shapes for downstream consumers, and an easy integration point for web apps, viewers, or model-serving pipelines.

Features

• Search Rijksmuseum collection by keyword, artist, date, and other filters
• Fetch artwork details (metadata, descriptive text, provenance)
• Serve image tiles suitable for deep-zoom viewers (z/x/y tile scheme)
• Expose user collection endpoints to list saved items
• Lightweight, self-hostable server with environment configuration
• Built with developer ergonomics in mind: simple JSON responses and example clients

Installation / Configuration

Clone the repository and run locally (Node.js-based example):

# Clone
git clone https://github.com/r-huijts/rijksmuseum-mcp.git
cd rijksmuseum-mcp

# Install
npm install

# Start
npm start

Environment variables (example .env):

PORT=3000
RIJKS_API_KEY=your_rijksmuseum_api_key_here
CACHE_TTL=3600
BASE_URL=http://localhost:3000

Run with Docker:

# Build image
docker build -t rijksmuseum-mcp .

# Run container (map port 3000)
docker run -e RIJKS_API_KEY=your_key_here -p 3000:3000 rijksmuseum-mcp

If the upstream Rijksmuseum API requires an API key, set it as RIJKS_API_KEY. Adjust PORT, CACHE_TTL and other settings to match your deployment.

Available Resources

The server provides a few primary endpoints. Below is a compact reference.

Example: search for “Rembrandt” (curl)

curl "http://localhost:3000/mcp/search?q=Rembrandt&page=1&per_page=20"

Example: get artwork metadata by ID

curl "http://localhost:3000/mcp/models/SK-A-1234"

Example: fetch a tile for a zoom viewer

curl "http://localhost:3000/mcp/tiles/SK-A-1234/10/512/256.jpg" --output tile.jpg

Responses are JSON for search and models; tile endpoints return image/jpeg tiles.

Use Cases

• Embed site-wide artwork search: call /mcp/search from a frontend search component to show results with thumbnails and brief metadata. Example (JS fetch):

const resp = await fetch('/mcp/search?q=landscape&per_page=12');
const data = await resp.json();
console.log(data.results);

• Build a deep-zoom viewer: use /mcp/models/{id} to obtain tile layout info (available zoom levels, tile size) and load tiles from /mcp/tiles/{id}/{z}/{x}/{y}.jpg in a viewer like OpenSeadragon.

• Enrich model prompts or galleries: fetch full artwork metadata and descriptive text with /mcp/models/{id} to provide context to an ML model or to populate a detail view.

• User-curated collections: surface a user’s saved items by calling /mcp/collections/{user} and then fetching model details or tiles for presentation.

Tips and Best Practices

• Cache extensively: artwork metadata and tiles are good candidates for CDN or reverse-proxy caching to reduce upstream calls.
• Rate limits: be respectful of upstream API quotas—configure local caching (CACHE_TTL) and backoff strategies.
• Security: keep RIJKS_API_KEY out of client code. Use the server as a gatekeeper and never expose secret keys to the browser.
• Tile fidelity: match your viewer’s tile size and zoom schema to the server’s tile generation to avoid mismatches.

Links and Resources

• Source code: https://github.com/r-huijts/rijksmuseum-mcp

If you need to extend functionality (additional filters, alternate tile schemes, or custom caching), the codebase is structured to be straightforward to modify and redeploy.