art-institute-chicago-mcp-server

---

概览

芝加哥艺术博物馆馆藏约有 133,000 件艺术品，另有艺术家、展览和语音导览站点。可使用筛选条件和分类计数进行搜索，读取包含来源信息和 IIIF 图像 URL 的完整记录，还可搜索语音导览文字稿。无需 API 密钥。

工具

工具	描述
artic_search_artworks	按文本和筛选条件搜索艺术品，提供分类计数并支持按日期排序
artic_get_artworks	获取最多 10 件艺术品的完整记录：描述、来源信息、历史记录、附带权利状态的图像 URL、相关媒体
artic_search_artists	按名称或 ID 查找艺术家、文化和组织，并提供可用的 Getty ULAN 标识符、生卒日期、艺术品数量及代表作品
artic_search_exhibitions	按文本、日期、艺术品 ID 或艺术家 ID 搜索过去、当前和即将举行的展览
artic_search_audio_guide	按文本搜索语音导览站点：标题、MP3 URL 和文字稿
artic_lookup_vocabulary	列出搜索筛选条件可接受的值及艺术品数量

资源

资源	描述
artic://artworks/{id}	单件艺术品的 JSON 记录，附有 API 许可文本和描述署名信息

对于不显示资源的客户端，artic_get_artworks 会返回相同的记录。

能力参考

搜索和词汇查询的限制最高为 1,000，响应会说明实际应用的上限：艺术品为 12，艺术家查询和展览为 25，语音导览为 2，词汇为 100。使用 next_page 翻页时，请保持请求的限制不变；页数乘以应用的数量不得超过 1,000。达到词汇上限时，请用 contains 缩小范围。

artic_search_artworks _工具

• query（每个词都必须匹配；"exact phrase"、-exclude 和 a | b 均可用）以及筛选条件 artist、artist_id、department、artwork_type、style、subject、classification、material、technique、theme、place_of_origin、gallery、year_from / year_to（日期范围重叠，负数表示公元前）、public_domain_only、on_view_only 和 has_image，这些条件以 AND 组合
• 每页最多 12 条（默认 10 条），从前 1,000 条匹配结果中返回；sort 可设为 relevance、date_asc 或 date_desc；若相关性排序没有查询文本，sort_applied 会报告 popularity
• facets 会为最多七个字段添加排名前 15 的值（artist 会统计每位署名艺术家，且每条记录都包含 artist_id）；limit: 0 只返回计数

---

artic_get_artworks _工具

• ids 最多接受 1,000 个条目（逗号分隔的字符串最长 100,000 个字符）；空值和重复项会被移除，艺术品页面 URL 也会被识别为 id。最多获取前 10 个；sections 可从 description 和 provenance（默认）、exhibition_history、publication_history 及 catalogue 中选择
• 记录按请求顺序返回。missing_ids 列出博物馆没有的 id；deferred_ids 列出因响应预算而暂缓的记录以及尚未尝试的 id，可再次传给同一工具
• include_related_media（默认开启）会加载最多 20 条关联讲座和语音导览点；返回 CC BY 描述文本时，始终会包含 description_attribution

---

artic_search_artists _工具

• 可使用 query（所有姓名词都必须匹配）或 ids，但不能同时使用；ids 最多接受 1,000 个条目（逗号分隔的字符串最长 100,000 个字符），最多获取前 25 个。查询模式还支持 artists_only（默认 true）、born_from / born_to，且每页最多返回 25 位人物
• 每位人物都包含 artwork_count、最多三个 sample_works（优先显示博物馆重点推荐的作品）、生卒年份和 alt_names；id 模式会报告 missing_ids 和 deferred_ids，可在下次调用时将其作为 ids 传入
• ulan_id 是博物馆有记录时提供的 Getty ULAN 标识符；其覆盖范围有限，且与其他工具使用的博物馆 id 不同

---

artic_search_exhibitions _工具

• query、when（current、upcoming、past 或默认的 any）、date_from / date_to（YYYY-MM-DD，按展期重叠匹配），以及精确的 artwork_id / artist_id 筛选条件，以 AND 组合；每页最多 25 条，从前 1,000 条匹配结果中返回
• 关系筛选仅涵盖博物馆记录的关联；未记录关联并不能证明某件艺术品或某位艺术家从未参加过某场展览
• sort 可设为 relevance、start_desc 或 start_asc；有查询时默认为 relevance，没有查询时默认为 start_desc；status 是博物馆使用的标签，并不表示展览是否正在开放（这由 when 表示）
• 如果博物馆列出了相关信息，每条记录都包含日期、展厅、摘要、网页、图像、artist_ids 和展出的 artworks

---

artic_search_audio_guide _工具

• 必须提供 query，用于匹配讲解点标题和文字稿中的词语（每个词都必须匹配）；每页最多返回两个完整讲解点（默认 2 个）
• 每个讲解点都包含 title、audio_url（MP3）和 transcript，但不包含艺术品 id；每个响应都包含 license_text 和 source_citation（内容仅供非商业教育和个人使用）

---

artic_lookup_vocabulary _工具

• vocabulary 为 department、artwork_type、style、subject、classification、material、technique、theme、place_of_origin 或 gallery；可选的 contains 子字符串（忽略大小写和重音符号，因此 applique 可找到 appliqué (technique)）、public_domain_only，以及最多 100 个值（默认 25）
• 值按出现频率从高到低返回，并包含 artwork_count，格式与 artic_search_artworks 中同名筛选器接受的格式完全一致；filter_param 指明该筛选器的名称

---

artic://artworks/{id} _资源

• 以 application/json 格式返回 { artwork, license_text, description_attribution?, notice? }，其中 artwork 是 artic_get_artworks 记录，包含默认部分和相关媒体
• 未知 ID 会返回 artwork_not_found；ID 可通过 artic_search_artworks 获取

功能

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

Art Institute 专属功能：

• 无需密钥即可访问芝加哥艺术博物馆公共 API（api.artic.edu/api/v1）；IIIF 图像 URL 根据每条记录生成（每张图像为 843 px；公有领域作品为 1686 px，并提供 IIIF 清单），不会获取图像
• 在该 API 每分钟 60 次的公开限制内统一控制请求速率；在 20 秒的期限内重试瞬时故障；使用进程内响应缓存（记录缓存 6 小时，搜索缓存 15 分钟，词汇表缓存 24 小时）
• 文本搜索要求每个词都匹配，因此总数准确无误，搜索无结果时会显示零条命中；结果保留博物馆的相关性排序
• 博物馆数据中占位年份（早于 −8000 或晚于 2100）不会出现在输出、年份筛选或日期排序中；date_display 始终是权威依据

便于 Agent 使用的输出：

• 权利信息随数据一同返回：每张图像都包含 image.rights（public_domain / in_copyright），仅允许复用的图像才提供 1686 px URL；原样返回 API 的 license_text；返回 CC BY 文本时包含 description_attribution；语音导览结果包含 source_citation
• 返回部分结果而非失败：artic_get_artworks 会报告 missing_ids 和 deferred_ids；如果相关媒体、艺术家计数等次级查询失败，仍会返回主要记录，并通过 notice 指明缺失内容
• 分页信息会说明下一步操作：totalCount、has_more、next_page；如果还有下一页、达到 1,000 条匹配上限，或零条命中时需要放宽筛选条件，则会提供相应的 notice

数据与许可

芝加哥艺术博物馆按内容类型对其 API 数据采用不同许可；服务会随每条作品、艺术家、展览和语音导览结果一并传递 API 自带的 license_text：

内容	条款
作品元数据、艺术家、展览、词汇表术语、相关媒体	CC0
作品的 description 文本	CC BY 4.0：注明芝加哥艺术博物馆，并引用记录的 web_url
作品图像	仅可复用公有领域作品的图像（image.rights: "public_domain"，CC0）；其他图像需要进行权利核查
语音导览内容	仅限非商业性教育和个人使用；须保留版权声明并注明来源

本服务是一个独立项目，与芝加哥艺术博物馆无关联，也未获其认可。

已知限制

• 未使用已认证密钥时，任何搜索最多只能访问前 1,000 条匹配结果。范围较广的问题需要使用筛选条件或分面。
• API 的每分钟 60 次请求限制按出口 IP 计算，因此同一 IP 后的所有客户端共享此限制。无法在 20 秒预算内启动的调用会以 rate_limited 失败。
• 策展文本较少：约 10% 的艺术作品有 description，而在一般样本中，94% 的作品没有来源信息。约 1% 的艺术家有传记；没有国籍字段，只有 artist_display 文本。
• 约 15 件艺术作品的年份是占位年份，约 4,900 件没有日期；这两类都不会匹配年份筛选条件。
• 博物馆数据中的某些词汇标题会截断为 40 个字符（gelatin silver (developing-out-paper) pr）。请按 artic_lookup_vocabulary 列出的值传入。
• API 防火墙会拒绝文本中包含 <script> 等标记的请求；调用会以 request_blocked 失败。
• 约 4% 的展览列出了其艺术作品。
• 语音导览站点没有关联艺术作品。有些标题是文件名，有些转录文本是西班牙语。
• 博物馆取消发布或替换图片后，图片 URL 可能会失效；相关性排序遵循博物馆的排名，可能会变化。

入门

公共托管实例

可通过 https://art-institute-chicago.caseyjhand.com/mcp 使用公共实例 — 无需安装。该实例提供 Streamable HTTP；每个客户端的配置格式各不相同。

对于 Claude Code：

claude mcp add --transport http art-institute-chicago-mcp-server https://art-institute-chicago.caseyjhand.com/mcp

对于 Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "art-institute-chicago-mcp-server": {
      "type": "streamableHttp",
      "url": "https://art-institute-chicago.caseyjhand.com/mcp"
    }
  }
}

对于 Cursor（mcp.json）：

{
  "mcpServers": {
    "art-institute-chicago-mcp-server": {
      "url": "https://art-institute-chicago.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在“设置”→“连接器”下添加远程服务。

托管实例的所有调用方共享 api.artic.edu 每分钟 50 次请求的额度。如需持续使用，请运行自己的实例。

自托管 / 本地

将以下内容添加到 MCP 客户端配置文件中。无需 API 密钥；AIC_CONTACT 用于告知博物馆如何联系你（参见配置）。

{
  "mcpServers": {
    "art-institute-chicago-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/art-institute-chicago-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "AIC_CONTACT": "[email protected]"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "art-institute-chicago-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/art-institute-chicago-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "AIC_CONTACT": "[email protected]"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "art-institute-chicago-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "[email protected]", "ghcr.io/cyanheads/art-institute-chicago-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 密钥或账号。Art Institute API 要求客户端提供身份信息；请将 AIC_CONTACT 设置为电子邮件地址或 URL。

安装

1. 克隆代码库：

git clone https://github.com/cyanheads/art-institute-chicago-mcp-server.git

2. 进入目录：

cd art-institute-chicago-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set AIC_CONTACT

配置

变量	描述	默认值
AIC_CONTACT	博物馆可联系到你的电子邮件地址或 URL，会通过 AIC-User-Agent 标头发送。仅限可打印的 ASCII 字符；否则服务将拒绝启动。任何部署都应设置为你自己的信息。	https://github.com/cyanheads/art-institute-chicago-mcp-server
AIC_REQUESTS_PER_MINUTE	对 api.artic.edu 的每分钟出站请求数，范围为 1–600。此值低于 API 公布的 60 次限制；只有博物馆授予更高限制时才应调高。	50
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。会覆盖服务声明的模式。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry。	false

有关所有服务设置和常见框架覆盖项，请参阅 .env.example。

运行服务

本地开发

• 构建并运行生产版本：

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

• 运行检查和测试：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

项目结构

目录	用途
src/index.ts	createApp() 入口：注册工具和资源，设置服务说明，并启动和停止 API 服务。
src/config	使用 Zod 解析并验证 AIC_CONTACT 和 AIC_REQUESTS_PER_MINUTE。
src/mcp-server/tools	工具定义（*.tool.ts）及其共用的作品输出架构。
src/mcp-server/resources	artic://artworks/{id} 资源。
src/services/aic	Art Institute API 客户端：请求节流、重试、响应缓存、HTML 转文本、IIIF URL 构建，以及作品和艺术家记录构建器。
tests/	单元测试和集成测试，结构与 src/ 对应。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明：

• 处理器抛出异常，框架负责捕获——工具逻辑中不使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.enrich 处理分页和通知
• 在 src/mcp-server/*/definitions/index.ts 下的汇总文件中注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。