met-museum-mcp-server

---

概述

大都会艺术博物馆拥有跨越 5,000 年、超过 500,000 件藏品。可按关键词和筛选条件搜索、按部门浏览，并获取包含来源信息和 CC0 开放获取图像的完整藏品记录。

工具

工具	描述
met_list_departments	返回全部 19 个策展部门及其数字 ID 和显示名称
met_search_collections	按关键词搜索藏品，可选择仅匹配标题或标签；支持按部门、日期范围、媒介、地理位置、图像可用性、展出状态和重点推荐标记筛选
met_list_objects	无需关键词即可列出某个部门的所有藏品 ID、某个日期之后创建或修订的所有藏品 ID，或同时列出两者
met_get_object	获取一个或多个藏品 ID 的完整记录——元数据、来源信息、艺术家信息、CC0 图像 URL、标签和 Wikidata 链接；还可选择将最多 3 张 CC0 图像作为图像内容返回

功能参考

met_list_departments _工具

• 无需输入；返回全部 19 个策展部门，每个部门均包含数字 departmentId 和 displayName（例如 “埃及艺术”）
• departmentId 值可作为 met_search_collections 和 met_list_objects 的 departmentId 筛选条件
• 类型化错误：upstream_blocked、upstream_unavailable（大都会艺术博物馆在每次重试中均返回 500/502/503/504）、upstream_rate_limited（大都会艺术博物馆返回 429）以及 retry_deadline_exceeded（调用超出时间预算）

---

met_search_collections _工具

• 关键词 q（必填），默认匹配所有文本字段；若 matchField 指定为 "title" 或 "tags"，则仅匹配对应字段；"*" 匹配所有内容，可仅按筛选条件搜索。筛选条件：departmentId、medium（区分大小写，例如 "Paintings"）、dateBegin/dateEnd（整数年份，负数表示公元前，需同时设置）、一个 geoLocation、hasImages、isOnView 和 isHighlight（仅支持 true）
• 每页最多 500 个 ID（默认 20 个），通过 offset / nextOffset 分页，最多遍历前 10,000 条匹配结果；total 返回完整数量。在大都会艺术博物馆，departmentId 7（The Cloisters）和 17（Medieval Art）共用一个结果集，因此每页可能包含少于 limit 个 ID，并会通过 notice 标明
• 没有匹配结果时会返回带有 notice 的结果，而非错误；每个结果都会通过 effectiveQuery 回显已应用的查询。类型化错误：invalid_date_range、invalid_filter（q、medium 或 geoLocation 为空）、invalid_department、upstream_blocked、upstream_unavailable、upstream_rate_limited、retry_deadline_exceeded

---

met_list_objects _工具

• 筛选条件 departmentId（来自 met_list_departments）和 updatedSince（YYYY-MM-DD，当天及之后创建或修订的记录），可单独使用或同时使用；若两者都未设置，则返回整个馆藏（超过 500,000 个 ID）。每页最多 500 个 ID（默认 20 个），按升序排列，通过 offset / nextOffset 分页，深度不限
• 列表为空时会返回带有 notice 的结果，而非错误；每个结果都会通过 effectiveQuery 回显已应用的筛选条件。类型化错误：invalid_department、invalid_date（无效日期，例如 2026-02-30）、upstream_blocked、upstream_unavailable、upstream_rate_limited、retry_deadline_exceeded
• 列表最多缓存一小时，因此最近一小时内修订的记录可能暂时不会出现

---

met_get_object _工具

• 每次调用获取 20 个不同的 ID，ID 来自 met_search_collections 或 met_list_objects；最多可接收 500 个 ID，超出前 20 个的 ID 会列在 remainingIDs 中。索引可能会列出大都会艺术博物馆已不再提供的 ID，因此若某个 ID 返回 404，请将其移除
• 部分成功：每个 ID 的错误会列在 failed[] 中；只有所有 ID 都失败时，调用才会失败（all_not_found、upstream_blocked、upstream_rate_limited、retry_deadline_exceeded、upstream_unavailable 或 all_failed）。超过 60,000 字节 structuredContent 限额的记录会连同其大小列在 deferred[] 中，供重新请求
• 非公共领域对象（isPublicDomain / hasCC0Image）的 primaryImage、primaryImageSmall 和 additionalImages 均为空。includeImages: true 会将首批 3 条拥有 CC0 图像的记录（约 600 px）的图像作为内容附加到 content[] 中；每条记录的处理结果列在 images[] 中

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），提供结构化日志，并可选启用 OpenTelemetry 跟踪。

大都会艺术博物馆专属功能：

• 通过大都会艺术博物馆的公共馆藏 API，获取跨越 5,000 年、超过 500K 件艺术品的信息
• 来自 The Metropolitan Museum of Art 的 CC0 开放访问数据——无需许可或署名即可免费使用
• met_get_object 支持并行批量获取，并可配置并发数
• 每件藏品均包含关联数据——Getty ULAN 和 AAT URL，以及艺术家、标签和作品的 Wikidata 实体 URL
• 大都会艺术博物馆 API 的故障会以类型化错误的形式显示在每个工具中（403 防火墙拦截对应 upstream_blocked，5xx 对应 upstream_unavailable，429 对应 upstream_rate_limited），不会返回大都会艺术博物馆的原始错误页面
• 如果大都会艺术博物馆正在拦截请求、服务宕机或限流，met_get_object 会停止请求批次中的其余对象，因此异常批次只会产生少量请求

便于 Agent 使用的输出：

• 每条记录都包含来源信息：isPublicDomain 和 hasCC0Image 标志会显示哪些图像可以展示
• 部分失败报告：met_get_object 会返回 objects 和 failed 数组，因此成功结果会与各 ID 对应的错误一并返回
• 截断标记：met_search_collections 和 met_list_objects 会返回 total、returned、truncated、remaining、nextOffset 和解析后的 offset
• 字节预算说明：批次过大时，met_get_object 会在 deferred[] 中列出延后处理记录及其大小

快速开始

公共托管实例

可使用公共实例：https://met-museum.caseyjhand.com/mcp——无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

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

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。

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

也可使用 npx（无需 Bun）：

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

或使用 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"
      ]
    }
  }
}

使用 Streamable HTTP 时，设置传输类型并启动服务：

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

先决条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥——大都会艺术博物馆馆藏 API 是公开的，无需身份验证。

安装

1. 克隆仓库：

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

2. 进入目录：

cd met-museum-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

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

配置

所有配置都会在启动时通过 src/config/server-config.ts 中的 Zod 模式进行验证。

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http	stdio
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_SESSION_MODE	HTTP 会话模式：auto、stateful 或 stateless	stateless
MCP_AUTH_MODE	身份验证：none、jwt 或 oauth	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error）	info
LOGS_DIR	日志文件目录（仅 Node.js）	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败工具调用的参数和结果；按键名进行脱敏，并限制为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 字节（默认值为 16384）。自由格式值中的机密信息不会被脱敏。	false
OTEL_ENABLED	启用 OpenTelemetry 检测	false
MET_BASE_URL	大都会艺术博物馆馆藏 API 根地址；可覆盖为本地模拟服务	https://collectionapi.metmuseum.org/public/collection
MET_REQUEST_TIMEOUT_MS	每个 HTTP 请求的超时时间（毫秒）	10000
MET_CALL_DEADLINE_MS	单次工具调用的时间预算（毫秒），包含重试；超过预算时会以 retry_deadline_exceeded 失败	30000
MET_BATCH_CONCURRENCY	met_get_object 中的最大并行获取数	5

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

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

• 运行检查和测试：

  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

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/met-museum-mcp-server。默认会安装 OpenTelemetry 对等依赖；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口点 — 注册工具并初始化 Met 服务。
src/config	使用 Zod 解析并验证特定于服务的环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）— met_list_departments、met_search_collections、met_list_objects、met_get_object。
src/services/met	Met Collection API 客户端 — HTTP、调用截止时间、响应规范化、缓存的对象 ID 列表。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要概括如下：

• 处理程序抛出异常，框架负责捕获 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 通过 src/index.ts 中 createApp() 的数组注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

数据来源

数据来自 大都会艺术博物馆馆藏 API（CC0）。

许可证

Apache-2.0 — 详情请参阅 LICENSE。