io.github.cyanheads/met-museum-mcp-server

Official4 toolsLive

by cyanheads · TypeScript

Search the Met collection, browse by department or update date, fetch full records and CC0 images.

This MCP server exposes Metropolitan Museum of Art (MET) collection content via Model Context Protocol. It supports searching the collection, fetching full artwork records, and retrieving open-access images. Access is available over STDIO or Streamable HTTP. The project includes three tools and targets metadata and provenance workflows for a corpus of 500K+ artworks.

🛠️ Key Features

MET collection search
Full artwork record retrieval
Open-access images
Metadata and provenance access
3 MCP tools

🚀 Use Cases

Building AI agents that browse MET artwork metadata
Enriching cultural-heritage datasets with provenance details
Integrating open-access museum images into applications

⚡ Developer Benefits

MCP integration via Model Context Protocol
Transport support: STDIO and Streamable HTTP
TypeScript-oriented project (based on repository topics)

⚠️ Limitations

Description only specifies 500K+ artworks; it does not state coverage beyond the MET collection.

Topics

ai-agentsartbuncultural-heritagemcpmcp-servermodel-context-protocolmuseumopen-accesstypescript

Captured live from the server via tools/list.

met_list_departments

Return the 19 curatorial departments at The Metropolitan Museum of Art, each with its numeric departmentId and display name — the valid values for the departmentId filter on met_search_collections and met_list_objects.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

met_search_collections

Search the Metropolitan Museum of Art collection by keyword and optional filters. Returns the total match count and one page of matching object IDs, which met_get_object resolves to full records. Relevance is keyword-based, not semantic; department and geographic filters narrow results more than a longer query. Paging reaches only the first 10,000 matches of any search, so narrow a larger one with filters. The medium parameter takes an object classification as the Met spells it ("Paintings", "Sculpture"), not a material like "Oil on canvas". hasImages also includes copyrighted works; CC0 status is per object, from the isPublicDomain and hasCC0Image fields on met_get_object. isHighlight accepts true only. isOnView restricts results to works currently on display in a Met gallery.

Parameters11

q	string	required	Keyword query, matched across title, artist name, culture, medium, tags, and other text fields. Broad terms return large ID sets.
hasImages	boolean	optional	When true, restricts results to objects that have at least one associated image, including copyrighted works whose images cannot be reproduced; false restricts them to objects with none. For freely reusable CC0 images, confirm per object from the isPublicDomain and hasCC0Image fields on met_get_object.
isHighlight	boolean	optional	Opt-in filter, true only — omit it rather than passing false, which the search ignores. Selects objects the Met has designated as highlights — major works central to the collection.
isOnView	boolean	optional	When true, restricts results to objects currently on display in a Met gallery; false restricts them to objects not on view. The GalleryNumber field on the met_get_object record identifies the specific gallery.
medium	string	optional	Filter by object classification, case-sensitive and spelled as the Met spells it (e.g., "Paintings", "Drawings", "Prints", "Ceramics", "Sculpture", "Photographs", "Textiles") — "paintings" or "Painting" matches nothing. Maps to the classification field on the object, not the materials text, so a material description like "Oil on canvas" matches nothing either; met_get_object returns an object’s classification.
departmentId	integer	optional	Restrict results to one curatorial department. Valid IDs come from met_list_departments — the Met exposes a sparse set (roughly 1–21, with gaps); an unrecognized ID is rejected with an invalid_department error rather than silently widening the search. Can be combined with other filters.
geoLocation	array	optional	Filter by geographic origin: one country, region, or city, as a one-element array (e.g., ["France"]). The value is matched broadly against geography fields and artist nationality. Works best with the Egyptian Art, Greek and Roman Art, and similar departments that have well-populated geography fields.
dateBegin	integer	optional	Earliest object date (year, inclusive). Negative integers for BCE (e.g., -500 for 500 BCE). Requires dateEnd.
dateEnd	integer	optional	Latest object date (year, inclusive). Negative integers for BCE. Requires dateBegin.
limit	integer	optional	Maximum number of object IDs to return in this page. Paging reaches only the first 10,000 matches, so a page that would cross 10,000 is cut short there.
offset	integer	optional	Zero-based index of the first match to return (default 0); pass the nextOffset from a previous response to continue paging. Only the first 10,000 matches are reachable, so an offset at or beyond 10,000, or at or beyond a nonzero total, returns an empty page rather than an error. Matches with tied relevance can change order between requests, so an ID can occasionally repeat or be skipped at a page boundary.

Raw schema

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "description": "Keyword query, matched across title, artist name, culture, medium, tags, and other text fields. Broad terms return large ID sets."
    },
    "hasImages": {
      "description": "When true, restricts results to objects that have at least one associated image, including copyrighted works whose images cannot be reproduced; false restricts them to objects with none. For freely reusable CC0 images, confirm per object from the isPublicDomain and hasCC0Image fields on met_get_object.",
      "type": "boolean"
    },
    "isHighlight": {
      "description": "Opt-in filter, true only — omit it rather than passing false, which the search ignores. Selects objects the Met has designated as highlights — major works central to the collection.",
      "type": "boolean",
      "const": true
    },
    "isOnView": {
      "description": "When true, restricts results to objects currently on display in a Met gallery; false restricts them to objects not on view. The GalleryNumber field on the met_get_object record identifies the specific gallery.",
      "type": "boolean"
    },
    "medium": {
      "description": "Filter by object classification, case-sensitive and spelled as the Met spells it (e.g., \"Paintings\", \"Drawings\", \"Prints\", \"Ceramics\", \"Sculpture\", \"Photographs\", \"Textiles\") — \"paintings\" or \"Painting\" matches nothing. Maps to the classification field on the object, not the materials text, so a material description like \"Oil on canvas\" matches nothing either; met_get_object returns an object’s classification.",
      "type": "string"
    },
    "departmentId": {
      "description": "Restrict results to one curatorial department. Valid IDs come from met_list_departments — the Met exposes a sparse set (roughly 1–21, with gaps); an unrecognized ID is rejected with an invalid_department error rather than silently widening the search. Can be combined with other filters.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "geoLocation": {
      "description": "Filter by geographic origin: one country, region, or city, as a one-element array (e.g., [\"France\"]). The value is matched broadly against geography fields and artist nationality. Works best with the Egyptian Art, Greek and Roman Art, and similar departments that have well-populated geography fields.",
      "maxItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "description": "A country, region, or city (e.g., \"France\", \"Egypt\", \"New York\")."
      }
    },
    "dateBegin": {
      "description": "Earliest object date (year, inclusive). Negative integers for BCE (e.g., -500 for 500 BCE). Requires dateEnd.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "dateEnd": {
      "description": "Latest object date (year, inclusive). Negative integers for BCE. Requires dateBegin.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "limit": {
      "default": 20,
      "description": "Maximum number of object IDs to return in this page. Paging reaches only the first 10,000 matches, so a page that would cross 10,000 is cut short there.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "offset": {
      "default": 0,
      "description": "Zero-based index of the first match to return (default 0); pass the nextOffset from a previous response to continue paging. Only the first 10,000 matches are reachable, so an offset at or beyond 10,000, or at or beyond a nonzero total, returns an empty page rather than an error. Matches with tied relevance can change order between requests, so an ID can occasionally repeat or be skipped at a page boundary.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "q"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

met_list_objects

Browse the Metropolitan Museum of Art collection without a keyword: every object ID in one curatorial department, every object whose record was created or revised on or after a date, or both together. Returns the total count and one page of IDs in ascending order, which met_get_object resolves to full records. With no filter the list is the whole collection (over 500,000 IDs). departmentId takes an ID from met_list_departments; updatedSince takes a YYYY-MM-DD date and answers "what has the Met added or revised since this day". Paging has no depth limit — pass nextOffset to continue. For keyword, classification, place, or object-date filters use met_search_collections instead. A list is cached for up to an hour, so a record revised within the last hour may not appear yet.

Parameters4

departmentId	integer	optional	Restrict the list to one curatorial department. Valid IDs come from met_list_departments — the Met exposes a sparse set (roughly 1–21, with gaps); an unrecognized ID is rejected with an invalid_department error rather than answered with an empty list.
updatedSince	string	optional	List only objects whose record was created or revised on or after this date, the day itself included, as YYYY-MM-DD (e.g., "2026-09-01") — no time part and no other date format. A date later than the newest update returns an empty list, not an error.
limit	integer	optional	Maximum number of object IDs to return in this page.
offset	integer	optional	Zero-based index of the first ID to return (default 0); pass the nextOffset from a previous response to continue paging. IDs are in ascending order and every one is reachable; an offset at or past total returns an empty page rather than an error.

Raw schema

{
  "type": "object",
  "properties": {
    "departmentId": {
      "description": "Restrict the list to one curatorial department. Valid IDs come from met_list_departments — the Met exposes a sparse set (roughly 1–21, with gaps); an unrecognized ID is rejected with an invalid_department error rather than answered with an empty list.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "updatedSince": {
      "description": "List only objects whose record was created or revised on or after this date, the day itself included, as YYYY-MM-DD (e.g., \"2026-09-01\") — no time part and no other date format. A date later than the newest update returns an empty list, not an error.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "limit": {
      "default": 20,
      "description": "Maximum number of object IDs to return in this page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "offset": {
      "default": 0,
      "description": "Zero-based index of the first ID to return (default 0); pass the nextOffset from a previous response to continue paging. IDs are in ascending order and every one is reachable; an offset at or past total returns an empty page rather than an error.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

met_get_object

Fetch full records for one or more Met Museum object IDs. Accepts up to 20 IDs per call and returns partial success — a single 404 does not fail the whole batch; per-ID failures are reported separately. Object IDs come from met_search_collections (keyword search) or met_list_objects (browse by department or update date). Non-public-domain objects return empty image URLs. The constituents array is null for anonymous or unattributed works; tags and measurements are null when the Met records none. Records are returned whole and never truncated, so a batch of unusually large records may return fewer than requested — any that did not fit are listed in deferred[] with their sizes, to be re-requested in a follow-up call.

Parameters1

objectIDs

array

required

One or more Met object IDs to fetch. Maximum 20 per call. IDs come from met_search_collections or met_list_objects. A repeated ID is fetched and returned once, at its first position. Partial failures are reported per ID rather than failing the whole batch.

Raw schema

{
  "type": "object",
  "properties": {
    "objectIDs": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991,
        "description": "A Met object ID from met_search_collections or met_list_objects."
      },
      "description": "One or more Met object IDs to fetch. Maximum 20 per call. IDs come from met_search_collections or met_list_objects. A repeated ID is fetched and returned once, at its first position. Partial failures are reported per ID rather than failing the whole batch."
    }
  },
  "required": [
    "objectIDs"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md13 KBView on GitHub

@cyanheads/met-museum-mcp-server

Search the Metropolitan Museum of Art collection, fetch full artwork records and open-access images via MCP. STDIO or Streamable HTTP.

3 Tools

Version MCP SDK TypeScript

Public Hosted Server: https://met-museum.caseyjhand.com/mcp

Overview

The Metropolitan Museum of Art's public Collection API. Search the collection by keyword and filters, 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

Tool	Description
`met_list_departments`	Return all 19 curatorial departments with their numeric IDs and display names
`met_search_collections`	Search the collection by keyword with filters for department, date range, medium, geography, image availability, on-view status, and highlight designation
`met_get_object`	Fetch full records for one or more object IDs — metadata, provenance, artist info, CC0 image URLs, tags, and Wikidata links

Capability reference

`met_list_departments` _tool

No input required — returns all 19 curatorial departments in one call
Each entry pairs departmentId (numeric) with displayName (e.g., "European Paintings", "Egyptian Art")
departmentId values are the valid inputs for met_search_collections's departmentId filter

`met_search_collections` _tool

Keyword q (required) matches title, artist name, culture, medium, tags, and other text fields; broad terms return large ID sets
Filters: departmentId (validated against met_list_departments; an unrecognized ID is rejected), medium (a case-sensitive classification as the Met spells it — "Paintings", "Sculpture" — not a material like "Oil on canvas"), dateBegin/dateEnd (integer years, negative = BCE, both required together), geoLocation (one country/region/city), hasImages, isOnView
isHighlight accepts true only — the search ignores false, so omit the filter instead of passing it. Public-domain (CC0) status is read per object from met_get_object, not filtered at search
Paginate with limit (default 20, max 500) and offset (default 0); nextOffset continues where a page left off (null once no further page is reachable). Paging reaches only the first 10,000 matches of a search — total still reports the full count, and a response whose total exceeds 10,000 says so in a notice
Returns total, returned, truncated, remaining, nextOffset, and the resolved offset; object IDs resolve to full records via met_get_object (up to 20 per call)
Typed errors: no_results (its recovery names the filters that removed every match, or points at the keyword when it matches nothing on its own), invalid_date_range, invalid_filter (blank q, medium, or geoLocation), invalid_department — each carries a recovery hint

`met_get_object` _tool

Accepts 1–20 IDs per call; a repeated ID is fetched and returned once, at its first position
Partial-success batching — a 404 or fetch failure doesn't fail the whole call; failed[] reports per-ID error detail, and the call fails only when every ID fails (all_not_found / all_failed)
Full record: metadata, provenance, artist/constituent data (Getty ULAN + Wikidata URLs), controlled-vocabulary tags (Getty AAT + Wikidata), a nine-field geography findspot block, and structured measurements — sparse fields are empty string or null, never fabricated
Records are never truncated individually — a call whose combined records exceed a serialized-bytes budget returns fewer of them, listing the rest in deferred[] with sizes to re-request; content[] re-renders the admitted records, so the delivered response runs roughly twice the budget
isPublicDomain/hasCC0Image gate image URLs — non-public-domain objects return empty primaryImage, primaryImageSmall, and additionalImages
Canonical objectURL and per-object objectWikidata_URL for human follow-up and external enrichment

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

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 returns total, returned, truncated, remaining, nextOffset, and the resolved offset fields so agents know when to refine filters, increase limit, or page further with offset; the text rendering marks each page (truncated), (complete), (window end) when paging stops at the 10,000-match window short of total, or (offset beyond result set) when the offset ran past what paging reaches
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:

json

{
  "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.

json

{
  "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):

json

{
  "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:

json

{
  "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

Clone the repository:

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

Navigate into the directory:

cd met-museum-mcp-server

Install dependencies:

bun install

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.

Variable	Description	Default
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`	`stdio`
`MCP_HTTP_PORT`	HTTP server port	`3010`
`MCP_SESSION_MODE`	HTTP session mode: `auto`, `stateful`, or `stateless`. This server declares `stateless` in `createApp()`, so it applies whenever the variable is unset; an explicit value overrides it. (`auto`, the framework schema default, resolves to `stateful`.)	`stateless`
`MCP_AUTH_MODE`	Authentication: `none`, `jwt`, or `oauth`	`none`
`MCP_LOG_LEVEL`	Log level (`debug`, `info`, `warning`, `error`)	`info`
`LOGS_DIR`	Directory for log files (Node.js only)	`<project-root>/logs`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation	`false`
`MET_BASE_URL`	Met Collection API root; each endpoint appends its own version (`/v1.1/search`, `/v1/objects/{id}`, `/v1/departments`). A value ending in `/v1` or `/v1.1` is read as its root. Override for local stubs.	`https://collectionapi.metmuseum.org/public/collection`
`MET_REQUEST_TIMEOUT_MS`	Per-request HTTP timeout in milliseconds	`10000`
`MET_BATCH_CONCURRENCY`	Max parallel fetches in `met_get_object`	`5`

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

Directory	Purpose
`src/index.ts`	`createApp()` entry point — registers tools and inits the Met service.
`src/config`	Server-specific environment variable parsing and validation with Zod.
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`) — `met_list_departments`, `met_search_collections`, `met_get_object`.
`src/services/met`	Met Collection API client — HTTP, request timeout, response normalization.
`tests/`	Unit and integration tests mirroring `src/`.

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.

Install

Tools (4)

met_list_departmentsmet_search_collectionsmet_list_objectsmet_get_object

Configuration

Environment variables

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_SESSION_MODEdefault stateless

HTTP session mode: auto, stateful, or stateless. This server explicitly sets stateless; the framework schema default is auto.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

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

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

met_list_departments

met_search_collections

met_list_objects

met_get_object

@cyanheads/met-museum-mcp-server

Overview

Tools

Capability reference

met_list_departments tool

met_search_collections tool

met_get_object tool

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

Data attribution

License

Install

Configuration

Related servers

`met_list_departments` _tool

`met_search_collections` _tool

`met_get_object` _tool