@cyanheads/met-museum-mcp-server
Enriches artwork records retrieved from the Met Museum collection with Wikidata entity URLs for artists, tags, and works, letting agents follow linked-data references from objects to their Wikidata counterparts.
Public Hosted Server: https://met-museum.caseyjhand.com/mcp
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
Tool | Description |
| Return all 19 curatorial departments with their numeric IDs and display names |
| Search the collection by keyword, optionally matched in titles, tags, or artists and cultures only, with filters for department, date range, object type, geography, image availability, on-view status, and highlight designation |
| List every object ID in a department, every object created or revised since a date, or both, without a keyword |
| Fetch full records for one or more object IDs — metadata, provenance, artist info, CC0 image URLs, tags, and Wikidata links — optionally with up to 3 CC0 images as image content |
Related MCP server: open-museum-mcp
Capability reference
met_list_departments tool
No input; returns all 19 curatorial departments, each a numeric
departmentIdwith itsdisplayName(e.g., "Egyptian Art")departmentIdvalues are the valid input for thedepartmentIdfilter onmet_search_collectionsandmet_list_objectsTyped errors:
upstream_blocked,upstream_unavailable(the Met answered 500/502/503/504 through every retry),upstream_rate_limited(the Met answered 429), andretry_deadline_exceeded(the call's time budget ran out)
met_search_collections tool
Keyword
q(required), matched across all text fields unlessmatchFieldnarrows it to"title","tags", or"artistOrCulture"(the attributed artist or the culture);"*"matches everything, for a search by filters alone. Filters:departmentId,medium(one object type, case-sensitive, e.g."Paintings"; one object can match several, so counts split bymediumcan overlap),dateBegin/dateEnd(integer years, negative = BCE, set together; an object matches only when its whole date span lies inside the window), onegeoLocation(a whole place, case-sensitive, e.g."Greece"),hasImages,isOnView, andisHighlight(trueonly)Up to 500 IDs per page (default 20), paged by
offset/nextOffsetthrough the first 10,000 matches;totalreports the full count.departmentId7 (The Cloisters) and 17 (Medieval Art) share one result set at the Met, so a page can hold fewer thanlimitIDs, which anoticeflagsZero matches is a result with a
notice, not an error; every result echoes the applied query aseffectiveQuery. Typed errors:invalid_date_range,invalid_filter(a blankq,medium, orgeoLocation),invalid_department,upstream_blocked,upstream_unavailable,upstream_rate_limited,retry_deadline_exceeded
met_list_objects tool
Filters
departmentId(frommet_list_departments) andupdatedSince(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 byoffset/nextOffsetwith no depth limitAn empty list is a result with a
notice, not an error; every result echoes the applied filters aseffectiveQuery. Typed errors:invalid_department,invalid_date(an impossible date such as2026-02-30),upstream_blocked,upstream_unavailable,upstream_rate_limited,retry_deadline_exceededLists 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_collectionsormet_list_objects; a list of up to 500 is accepted, and the IDs past the first 20 come back inremainingIDs. The index can list IDs the Met no longer serves, so drop an ID that 404sPartial 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, orall_failed)Non-public-domain objects (
isPublicDomain/hasCC0Image) return emptyprimaryImage,primaryImageSmall, andadditionalImages.includeImages: trueattaches the CC0 image (about 600 px) of the first 3 records that have one as image content incontent[]only, with each record's outcome inimages[]
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_objectLinked 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_blockedfor a 403 firewall block,upstream_unavailablefor 5xx,upstream_rate_limitedfor 429), never as the Met's raw error pagemet_get_objectstops 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:
isPublicDomainandhasCC0Imageflags show which images can be displayedPartial failure reporting:
met_get_objectreturnsobjectsandfailedarrays, so successes arrive alongside per-ID errorsTruncation signaling:
met_search_collectionsandmet_list_objectsreturntotal,returned,truncated,remaining,nextOffset, and the resolvedoffsetPublished agent skill:
met-museum-guide(skill://met-museum-guide/SKILL.md) carries the checks for fetch budgets, attributions, date windows, searches past 10,000 matches, andgeoLocationmatches
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/mcpPrerequisites
Bun v1.4.4 or higher (or Node.js v24+).
No API key required — the Met Collection API is public and unauthenticated.
Installation
Clone the repository:
git clone https://github.com/cyanheads/met-museum-mcp-server.gitNavigate into the directory:
cd met-museum-mcp-serverInstall dependencies:
bun installConfigure 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.
Variable | Description | Default |
| Transport: |
|
| HTTP server port |
|
| HTTP session mode: |
|
| Authentication: |
|
| Log level ( |
|
| Directory for log files (Node.js only) |
|
| Log each failed tool call's arguments and result, redacted by key name and capped at |
|
| Enable OpenTelemetry instrumentation |
|
| Met Collection API root; override for local stubs |
|
| Per-request HTTP timeout in milliseconds |
|
| Time budget in milliseconds for one tool call, retries included; exceeding it fails with |
|
| Max parallel fetches in |
|
| Read a |
|
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:httpRun 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-serverThe 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
Directory | Purpose |
|
|
| Server-specific environment variable parsing and validation with Zod. |
| Tool definitions ( |
| Met Collection API client — HTTP, call deadline, response normalization, cached object-ID lists. |
| Unit and integration tests mirroring |
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
Handlers throw, framework catches — no
try/catchin tool logicUse
ctx.logfor request-scoped logging,ctx.statefor tenant-scoped storageRegister new tools via the arrays in
createApp()insrc/index.tsWrap 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 testData attribution
Data from The Metropolitan Museum of Art Collection API (CC0).
License
Apache-2.0 — see LICENSE for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Art MCP — Metropolitan Museum of Art Collection API (free, no auth)
Unlock a world of art with the Met Museum MCP! Use the 'search_artworks' API to find stunning
Victoria and Albert Museum (V&A) Collections MCP. Keyless. Wraps the V&A Collections API v2.
Query SEC EDGAR filings, XBRL financials, and company data via MCP. STDIO or Streamable HTTP.
Related MCP Servers
- AlicenseAqualityDmaintenanceA MCP Server that lets user ask AI models to discover the collection of the Metropolitan Museum of Art. Adds the discovered art works as Resources on the server.4211 npm36MIT
- AlicenseAqualityBmaintenanceFederated, license-verified search across open-access museum collections — currently The Met, Cleveland, AIC, Wikimedia Commons, and Europeana, with more being added. Strict-default-deny rights gate accepts only CC0 / Public Domain Mark, returning reuse-safe artwork with citations in three styles.5191 npm15MIT
- AlicenseNot gradedqualityBmaintenanceSearch artists, releases, recordings, works, and labels; traverse relationships; resolve ISRC/ISWC/barcode; fetch cover art via MCP. STDIO or Streamable HTTP.229 npm2Apache 2.0
- AlicenseAqualityDmaintenanceMCP server for searching museum collections and viewing artwork images and metadata from multiple museums, including the Met, Art Institute of Chicago, Rijksmuseum, and more.411 npm2MIT