Met Museum MCP Server README

Overview

The Metropolitan Museum of Art's collection of 500,000+ works spanning 5,000 years. Search by keyword and filters, browse by department, and fetch full object records with provenance and CC0 open-access images.

Tools

Capability reference

met_list_departments _tool

• No input; returns all 19 curatorial departments, each a numeric departmentId with its displayName (e.g., "Egyptian Art")
• departmentId values are the valid input for the departmentId filter on met_search_collections and met_list_objects
• Typed errors: upstream_blocked, upstream_unavailable (the Met answered 500/502/503/504 through every retry), upstream_rate_limited (the Met answered 429), and retry_deadline_exceeded (the call's time budget ran out)

met_search_collections _tool

• Keyword q (required), matched across all text fields unless matchField narrows it to "title" or "tags"; "*" matches everything, for a search by filters alone. Filters: departmentId, medium (case-sensitive, e.g. "Paintings"), dateBegin/dateEnd (integer years, negative = BCE, set together), one geoLocation, hasImages, isOnView, and isHighlight (true only)
• Up to 500 IDs per page (default 20), paged by offset / nextOffset through the first 10,000 matches; total reports the full count. departmentId 7 (The Cloisters) and 17 (Medieval Art) share one result set at the Met, so a page can hold fewer than limit IDs, which a notice flags
• Zero matches is a result with a notice, not an error; every result echoes the applied query as effectiveQuery. Typed errors: invalid_date_range, invalid_filter (a blank q, medium, or geoLocation), invalid_department, upstream_blocked, upstream_unavailable, upstream_rate_limited, retry_deadline_exceeded

met_list_objects _tool

• Filters departmentId (from met_list_departments) and updatedSince (YYYY-MM-DD, records created or revised on or after that day), alone or together; with neither, the whole collection (over 500,000 IDs). Up to 500 IDs per page (default 20) in ascending order, paged by offset / nextOffset with no depth limit
• An empty list is a result with a notice, not an error; every result echoes the applied filters as effectiveQuery. Typed errors: invalid_department, invalid_date (an impossible date such as 2026-02-30), upstream_blocked, upstream_unavailable, upstream_rate_limited, retry_deadline_exceeded
• Lists are cached for up to an hour, so a record revised in the last hour may not appear yet

met_get_object _tool

• Fetches 20 distinct IDs per call, from met_search_collections or met_list_objects; a list of up to 500 is accepted, and the IDs past the first 20 come back in remainingIDs. The index can list IDs the Met no longer serves, so drop an ID that 404s
• Partial success: per-ID errors land in failed[], and the call fails only when every ID does (all_not_found, upstream_blocked, upstream_rate_limited, retry_deadline_exceeded, upstream_unavailable, or all_failed). Records past a 60,000-byte structuredContent budget are listed in deferred[] with their sizes, to re-request
• Non-public-domain objects (isPublicDomain / hasCC0Image) return empty primaryImage, primaryImageSmall, and additionalImages. includeImages: true attaches the CC0 image (about 600 px) of the first 3 records that have one as image content in content[] only, with each record's outcome in images[]

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Met Museum-specific:

• 500K+ artworks spanning 5,000 years from the Met's public collection API
• CC0 open-access data from The Metropolitan Museum of Art — free to use without permission or attribution
• Parallel batch fetching with configurable concurrency for met_get_object
• Linked data on every object — Getty ULAN and AAT URLs, Wikidata entity URLs for artists, tags, and works
• Met API failures surface on every tool as typed errors (upstream_blocked for a 403 firewall block, upstream_unavailable for 5xx, upstream_rate_limited for 429), never as the Met's raw error page
• met_get_object stops requesting the rest of a batch once the Met is blocking, down, or throttling, so a bad batch costs only a few requests

Agent-friendly output:

• Provenance on every record: isPublicDomain and hasCC0Image flags show which images can be displayed
• Partial failure reporting: met_get_object returns objects and failed arrays, so successes arrive alongside per-ID errors
• Truncation signaling: met_search_collections and met_list_objects return total, returned, truncated, remaining, nextOffset, and the resolved offset
• Byte-budget disclosure: met_get_object lists deferred[] records with their sizes when a batch is too large

Getting started

Public Hosted Instance

A public instance is available at https://met-museum.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "met-museum-mcp-server": {
      "type": "streamable-http",
      "url": "https://met-museum.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "met-museum-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/met-museum-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "met-museum-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/met-museum-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "met-museum-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/met-museum-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• No API key required — the Met Collection API is public and unauthenticated.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/met-museum-mcp-server.git

2. Navigate into the directory:

cd met-museum-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env as needed (all vars are optional)

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts.

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  shCopy

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  shCopy

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t met-museum-mcp-server .
docker run --rm -p 3010:3010 met-museum-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/met-museum-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools via the arrays in createApp() in src/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

Data attribution

Data from The Metropolitan Museum of Art Collection API (CC0).

License

Apache-2.0 — see LICENSE for details.