Met Museum Mcp Server

io.github.cyanheads由 GitHub 帳號 cyanheads 發布v0.10.1更新於 Nov 15, 2026

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

已驗證Streamable HTTP可網頁執行知識與記憶媒體與設計

概覽

AI 產生的概覽

搜尋與瀏覽大都會藝術博物館公開館藏,並取得完整藏品紀錄、來源資訊與 CC0 圖像。

可以做什麼
  • 列出 19 個策展部門及其數字 ID
  • 依關鍵字搜尋館藏,可限定比對標題、標籤或藝術家/文化,並依部門、年代範圍、材質、地理、是否有圖、是否展出、是否重點展品篩選
  • 不需關鍵字即可依部門、依某日期之後建立或修訂的紀錄,或兩者合併瀏覽藏品 ID
  • 每次呼叫取得最多 20 個藏品 ID 的完整紀錄,含來源、藝術家資訊、CC0 圖像連結、標籤與 Wikidata 連結,可選擇附帶最多 3 張 CC0 圖像
適用情境
適合需要回答大都會館藏中特定藝術品、藝術家、文化或年代問題,或為研究、教學與內容製作蒐集開放取用圖像與編目中介資料時使用。
執行需求
可使用公開託管的 Streamable HTTP 端點(免安裝),或透過 npx/bunx/Docker 在本機執行;本機執行需 Node.js v24+ 或 Bun v1.4.4+。不需 API 金鑰,大都會館藏 API 公開且免驗證。需要連線至大都會 API 的網路存取;所有設定變數皆為選用。
安裝前請注意
大都會防火牆可能在約 3 分鐘內約 22 次請求後封鎖伺服器位址約 20 分鐘,大量批次抓取會失敗,應只取所需紀錄。搜尋最多只能翻到前 10,000 筆符合項目。非公有領域藏品不傳回圖像連結,hasImages 也可能包含無可用圖像的受著作權保護作品。館藏文字是博物館撰寫的資料,不是指令。選用的失敗酬載日誌可能記錄工具參數,自由文字中的密鑰不會被遮蔽。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Met Museum Mcp Server,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Web executable,透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

交給代理程式安裝

把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式,或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南,先向你展示發布者、端點和登入方式,經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。

閱讀 https://sourceweft.com/mcp/io.github.cyanheads%2Fmet-museum-mcp-server/install.md,並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前,先告訴我它的發布者、端點和登入方式,等我確認。不要把 API 金鑰寫進命令或我會提交的檔案;問我金鑰應從哪裡取得。

檢視代理程式所依據的安裝指南

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

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

README

@cyanheads/met-museum-mcp-server

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

4 Tools


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

ToolDescription
met_list_departmentsReturn all 19 curatorial departments with their numeric IDs and display names
met_search_collectionsSearch 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
met_list_objectsList every object ID in a department, every object created or revised since a date, or both, without a keyword
met_get_objectFetch 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

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", "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 by medium can overlap), dateBegin/dateEnd (integer years, negative = BCE, set together; an object matches only when its whole date span lies inside the window), one geoLocation (a whole place, case-sensitive, e.g. "Greece"), 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)
  • 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
  • Published 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, and geoLocation matches

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:

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

Prerequisites

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

Installation

  1. Clone the repository:
sh
git clone https://github.com/cyanheads/met-museum-mcp-server.git
  1. Navigate into the directory:
sh
cd met-museum-mcp-server
  1. Install dependencies:
sh
bun install
  1. Configure environment:
sh
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.

VariableDescriptionDefault
MCP_TRANSPORT_TYPETransport: stdio or httpstdio
MCP_HTTP_PORTHTTP server port3010
MCP_SESSION_MODEHTTP session mode: auto, stateful, or statelessstateless
MCP_AUTH_MODEAuthentication: none, jwt, or oauthnone
MCP_LOG_LEVELLog level (debug, info, warning, error)info
LOGS_DIRDirectory for log files (Node.js only)<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADSLog each failed tool call's arguments and result, redacted by key name and capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (default 16384). A secret inside a free-form value is not redacted.false
OTEL_ENABLEDEnable OpenTelemetry instrumentationfalse
MET_BASE_URLMet Collection API root; override for local stubshttps://collectionapi.metmuseum.org/public/collection
MET_REQUEST_TIMEOUT_MSPer-request HTTP timeout in milliseconds10000
MET_CALL_DEADLINE_MSTime budget in milliseconds for one tool call, retries included; exceeding it fails with retry_deadline_exceeded30000
MET_BATCH_CONCURRENCYMax parallel fetches in met_get_object5
MET_CLAMP_LIMITSRead a limit above 500 on met_search_collections and met_list_objects as a 500-ID page, with a notice, instead of rejecting it; false makes 500 the schema maximumtrue

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

Running the server

Local development

  • Build and run:

    sh
    # One-time buildbun run rebuild
    # Run the built serverbun run start:stdio# orbun run start:http
  • Run checks and tests:

    sh
    bun run devcheck   # Lint, format, typecheck, securitybun run test       # Vitest test suitebun run lint:mcp   # Validate MCP definitions against spec

Docker

sh
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

DirectoryPurpose
src/index.tscreateApp() entry point — registers tools and inits the Met service.
src/configServer-specific environment variable parsing and validation with Zod.
src/mcp-server/toolsTool definitions (*.tool.ts) — met_list_departments, met_search_collections, met_list_objects, met_get_object.
src/services/metMet Collection API client — HTTP, call deadline, response normalization, cached object-ID lists.
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:

sh
bun run devcheckbun run test

Data attribution

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

License

Apache-2.0 — see LICENSE for details.

來源:README.md,提交 ae0754c

工具

4

met_list_departments

List Met 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.

無需輸入參數。

met_search_collections

Search Met Collection

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 one object type 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.

輸入參數q必填limitmediumoffsetdateEndisOnViewdateBeginhasImagesmatchFieldgeoLocationisHighlightdepartmentId

met_list_objects

List Met 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, object-type, 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.

輸入參數limitoffsetdepartmentIdupdatedSince

met_get_object

Get Met Objects

Fetch full records for one or more Met Museum object IDs. Fetches up to 20 distinct IDs per call; a list of up to 500 (a full search or list page) is accepted, and the distinct IDs past the first 20 come back unrequested in remainingIDs for a follow-up call. 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. Set includeImages to also receive the CC0 images of up to 3 returned records as image content a vision-capable model can look at.

輸入參數objectIDs必填includeImages

版本歷史

8
  1. v0.10.1最新Nov 15, 2026
  2. v0.10.0Nov 4, 2026
  3. v0.9.0Oct 15, 2026
  4. v0.8.0Oct 4, 2026
  5. v0.7.0Sep 30, 2026
  6. v0.6.0Sep 25, 2026
  7. v0.5.3Sep 19, 2026
  8. v0.5.2Sep 16, 2026

評分

已滿足適用檢查項的 100%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分
  • 已宣告認證方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分