Met Museum Mcp Server

Overview

The Metropolitan Museum of Art's public Collection API. Search the collection by keyword and filters, or browse it by department and update date, then fetch full object records — metadata, provenance, and CC0 open-access images — from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

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 every object, for a search by filters alone; an accession number from a label ranks its object first. Plus filters: departmentId, medium (a case-sensitive classification as the Met spells it — "Paintings", not "Oil on canvas"), dateBegin/dateEnd (integer years, negative = BCE, set together), one geoLocation, hasImages, isOnView, and isHighlight (true only)
• departmentId 7 (The Cloisters) and 17 (Medieval Art) share one search result set at the Met: each page keeps only the requested department's IDs, while total and paging count both, so a page can hold fewer than limit IDs; a notice says so, and met_list_objects gives exact department membership
• Up to 500 IDs per page (default 20; a limit up to 10,000 reads a 500-ID page, with a notice), paged by offset / nextOffset through the first 10,000 matches only; total still reports the full count, with a notice when it exceeds 10,000
• Zero matches is a result, not an error: total: 0 with a notice saying whether the keyword matches nothing or the filters removed every match, and which filters to correct or drop. 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; a limit up to 10,000 reads a 500-ID page, with a notice), in ascending order, paged by offset / nextOffset with no depth limit
• Typed errors: invalid_department, invalid_date (an impossible date such as 2026-02-30), upstream_blocked, upstream_unavailable, upstream_rate_limited, retry_deadline_exceeded; an empty list is a result, not an error, with a notice naming the filters, and every result echoes the applied filters as effectiveQuery
• Each list is cached for up to an hour, so a record revised within the last hour may not appear yet

met_get_object _tool

• 20 distinct IDs fetched per call, from met_search_collections or met_list_objects; a repeated ID is fetched and returned once. A list of up to 500 (a full page) is accepted, and the distinct IDs past the first 20 come back unrequested in remainingIDs, with a notice
• Partial success: per-ID errors land in failed[], and the call fails only when every ID does — all_not_found when every ID was a 404, upstream_blocked when the Met's firewall refused a request, upstream_rate_limited when the Met answered 429, retry_deadline_exceeded when every fetch ran out of the call's time budget, upstream_unavailable when a fetch met a Met API outage, and all_failed otherwise; records past a 60,000-byte structuredContent budget are listed in deferred[] with their sizes, to re-request
• isPublicDomain / hasCC0Image gate image URLs — non-public-domain objects return empty primaryImage, primaryImageSmall, and additionalImages; sparse fields are empty or null, never fabricated
• includeImages: true attaches the CC0 web-display image (about 600 px on the long edge) of the first 3 returned records that have one, as image content after a caption naming the object, and images[] gives each returned record's outcome (attached, no_cc0_image, over_cap, unavailable). The bytes ride content[] only, so a client that passes the model only structuredContent won't show them
• The Artist line carries the full attribution and role — artistPrefix ("Style of"), the name, artistSuffix, and artistRole ("Patron") — so a follower's work or a patron never reads as the named artist's own; rightsAndReproduction names the rights holder on the copyrighted works that carry one, beside accessionYear
• reign ("Joint reign of Hatshepsut and Thutmose III") sits beside period and dynasty, and portfolio ("Birds of America, plate LXXI") names a print's series and plate; both are empty on most records
• metadataDate is the record's last revision, the timestamp met_list_objects updatedSince compares; departmentId resolves the record's department name (five differ from met_list_departments) to the ID met_list_objects and met_search_collections take, or null when the name is not recognized
• The search index can list IDs the object endpoint no longer serves, so a 404's guidance is to drop the ID rather than search for it again

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
• A 403 from the Met's firewall surfaces on every tool as upstream_blocked, non-retryable: the block covers the server's address for minutes, so the recovery is to wait and send fewer requests
• A 500, 502, 503, or 504 that outlasts the retries surfaces on every tool as upstream_unavailable; once every fetch in flight has failed without the Met answering any ID, met_get_object stops requesting the rest of the batch, so a 5xx outage costs at most MET_BATCH_CONCURRENCY × 4 requests (20 at the default) however many IDs were asked for
• A 429 that outlasts the retries, or asks for a wait longer than they or the call's time budget allow, surfaces on every tool as upstream_rate_limited, its message naming the wait the Met asked for; met_get_object then stops requesting the rest of the batch, so a throttled batch costs at most MET_BATCH_CONCURRENCY requests (5 at the default) with a long Retry-After and MET_BATCH_CONCURRENCY × 4 (20) without one
• No error carries the Met's HTML or JSON error page — an HTTP failure reaches the caller as its code, message, and status, or, inside a met_get_object batch, as that ID's failed[] message

Agent-friendly output:

• Provenance on every record — isPublicDomain and hasCC0Image flags distinguish CC0 objects from works with inaccessible images, so agents can reason about what they can actually display
• Partial failure reporting — met_get_object returns objects and failed arrays so callers receive successful records alongside structured per-ID error context
• Truncation signaling — met_search_collections and met_list_objects return total, returned, truncated, remaining, nextOffset, and the resolved offset; the text marks each page (truncated), (complete), or (offset beyond result set), and search adds (window end) for a page that stops at its 10,000-match window short of total
• Byte-budget disclosure — met_get_object reports deferred[] records with their sizes when a batch exceeds its serialized-response budget, so callers can size a follow-up call precisely

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:

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

• Run checks and tests:

  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.