whitney-museum-mcp-server
whitney-mcp-ts
一个用于惠特尼博物馆公共 API 的 MCP 服务器。可从 Claude Desktop 或任何 MCP 客户端搜索馆藏、艺术家、展览、活动和语音导览。
TypeScript,仅 stdio,友好的参数映射到 API 的 Ransack 语法,附带署名,并且响应经过裁剪,以便在模型的上下文中保持可控。
惠特尼的 API 是开放且无需认证的;不需要 API 密钥。
安装
npx whitney-mcp-ts或者从源码安装:
git clone https://github.com/mildlydiverting/whitney-mcp-ts.git
cd whitney-mcp-ts
npm install
npm run build需要 Node 20 或更高版本。
Related MCP server: Wikipedia MCP Server
Claude Desktop
添加到 claude_desktop_config.json:
{
"mcpServers": {
"whitney": {
"command": "npx",
"args": ["-y", "whitney-mcp-ts"]
}
}
}如果从源码运行,则指向构建产物:
{
"mcpServers": {
"whitney": {
"command": "node",
"args": ["/absolute/path/to/whitney-mcp-ts/dist/index.js"]
}
}
}退出并重新打开 Claude Desktop。配置文件不会展开 ~,所以请使用完整路径。
工具
工具 | 功能 |
| 按标题、艺术家、分类、媒介、日期、展出状态搜索 27,000+ 件作品 |
| 单件作品的完整记录——尺寸、致谢行、描述、图片 URL |
| 搜索 7,000+ 位艺术家;可按收藏、双年展、展出状态筛选 |
| 艺术家的完整记录,包括传记、Getty ULAN 和 Wikidata ID |
| 指定艺术家的作品 |
| 包含指定艺术家的展览 |
| 自 1931 年以来的展览,支持日期筛选 |
| 单个展览记录 |
| 自 2008 年以来的讲座、导览和节目 |
| 自 2009 年以来发布的语音导览 |
| 任意端点,支持原始 Ransack 谓词 |
预期效果
搜索返回精简记录。
惠特尼的记录包含冗长的 HTML 描述和传记,因此搜索只提供基本信息,而 whitney_get_* 提供全部内容。散文文本截断为 2,000 个字符,整个响应截断为 25,000 个字符。
分页每页 30 条。
这是 API 的页面大小。page 选择页码,limit 进一步裁剪——默认值为 10,可防止宽泛搜索淹没你的上下文。
搜索语法为 Ransack
谓词嵌套在 q 下(_eq、_cont、_cont_all_split、_gteq 等),排序在 q[s] 下。类型化工具将友好的参数映射到这些谓词上。whitney_query 直接暴露原始谓词,用于类型化工具无法覆盖的任何情况。
艺术家和艺术品字段已显式映射。
展览、活动、导览和页面则通过通用摘要器处理:去除 HTML,时间戳缩短为日期,相对 URL 转为绝对 URL,删除内部外键。博物馆表示其字段集可能会变化,因此没有硬编码任何不必要的内容。使用 limit: 1 运行搜索以查看真实字段名,然后使用 filters 处理任何特定需求。
署名
每个响应都以一行来源信息结尾,注明博物馆名称并链接其条款。详细记录还包含两个署名字段:
rights— 版权声明,从惠特尼自己的描述文本中提取citation— 现成的 Markdown 行,例如:
Edward Hopper, Early Sunday Morning, 1930. Whitney Museum of American Art, © Heirs of Josephine N. Hopper/Licensed by Artists Rights Society (ARS), New York.
请注意,权利持有者通常不是艺术家。在十件作品的样本中,有九件不同——遗产、基金会以及 ARS 和 VAGA 等权利组织。因此,rights 值得阅读而不是假设;这是惠特尼条款要求你保留的声明。
没有版权声明的作品(大多是较旧的材料)的引用会在博物馆链接之后结束。
批量数据
对于大规模数据,不要通过 API 分页。惠特尼在 https://github.com/whitneymuseum/open-access 发布了艺术家和艺术品 CSV 文件,采用 CC0 许可。
已知 API 怪癖
sort: "random"不能可靠地随机化。请求三件随机作品返回了同一艺术家的三个连续入藏编号。如果你需要真正的随机性,请改为请求随机页码。艺术品上的
display_date是自由文本——"1915–1931, printed 1976–1977"——因此日期范围在那里不起作用。展览和活动有真实的时间戳,starts_on_or_after/starts_on_or_before可对这些进行筛选。在世艺术家的
death_year为"0"。不要对它进行算术运算。Ransack 会忽略它无法识别的谓词而不是报错,因此拼写错误的字段会静默返回所有内容。请检查你的结果数量。
安全性
惠特尼的 API 不需要密钥,因此没有凭据,没有可泄露的内容,也无需配置。
每个工具都是只读的。服务器仅向 whitney.org 发出 GET 请求,没有其他操作——不访问文件系统,不执行 shell,不写入。端点名称来自固定列表,记录 ID 经过 URL 编码,筛选参数通过 URLSearchParams 处理。
一个已知的限制:HTML 到 Markdown 的转换使用了带有嵌套量词的正则表达式,在故意构造的畸形输入上可能会严重回溯。输入来自惠特尼自己的 CMS 而不是用户,所以如果发生这种情况,说明纽约那边出了大问题,可能不是我的错。
如果你发现问题,请提交 issue。
开发
npm test # unit tests, offline
npm run test:canary # live checks against the Whitney API
npm run inspect # MCP Inspector against the built server金丝雀测试套件每月在 CI 中运行。它用于捕捉惠特尼更改字段名的情况——这是单元测试无法发现的失败模式,因为单元测试针对保存的固定数据运行。
许可证
代码:MIT 许可证。
惠特尼提供 API 时附带了以下说明:
通过此 API 访问的数据可能受惠特尼美国艺术博物馆及第三方的版权和其他限制的保护。你可以将此数据用于非商业教育和个人用途,以及法律授权的"合理使用",前提是你同时保留材料中包含的所有版权和其他专有声明,并注明材料的作者和来源。
在基于它构建任何公开内容之前,请阅读他们的条款:https://whitney.org/about/website/api。
请注意,上面链接的 CSV 数据集采用 CC0 许可,可能比 API 条款更宽松。
与惠特尼美国艺术博物馆无关。这是围绕其公共 API 的第三方封装,文档位于 https://whitney.org/about/website/api。
致谢
另请参阅 Sam Parsons 的 whitney-museum-mcp —— 一个基于同一 API 的 Python/FastMCP 服务器,支持 Docker 和 HTTP 传输。
感谢惠特尼的数字团队发布了 API,并对其进行了适当的文档记录。还感谢他们撰写了明确表示使用 claude code 的优质博客文章,因为这让我对用 vibe coding 完成整个项目感到不那么内疚。
Available Tools
11 toolswhitney_artist_artworksList an artist's artworksARead-onlyIdempotent
List the collection works by one artist.
Args:
id (string): artist ID
page (number, default 1), limit (number, 1-30, default 10)
response_format ('markdown' | 'json', default 'markdown')
Returns: { total, count, page, has_more, next_page?, results[] } with slim artwork records.
Use this rather than whitney_search_artworks with an artist name — it matches on the artist record rather than the credit line, so collaborative and attributed works are handled correctly.
Inputs: id (required), page, limit, response_format. Returns: note, page, count, total, +4 more
whitney_artist_exhibitionsList an artist's exhibitionsARead-onlyIdempotent
List Whitney exhibitions featuring one artist.
Args:
id (string): artist ID
page (number, default 1), limit (number, 1-30, default 10)
response_format ('markdown' | 'json', default 'markdown')
Returns: { total, count, page, has_more, next_page?, results[] }.
Exhibition fields are passed through generically (HTML stripped, long prose truncated), because the Museum documents these fields as subject to change. Coverage is fuller for recent decades than for the Museum's early history.
Inputs: id (required), page, limit, response_format. Returns: note, page, count, total, +4 more
whitney_get_artistGet a Whitney artistARead-onlyIdempotent
Fetch one artist's full record, including their biography where the Museum has published one.
Args:
id (string): TMS ID or 'T'-prefixed reference
response_format ('markdown' | 'json', default 'markdown')
Returns: { record: { id, name, sort_name, dates, birth_year, death_year, in_collection, in_biennial, in_artport, on_view, ulan_id, wikidata_id, biography, page_url } }
The biography is stripped of HTML and truncated. ulan_id (Getty ULAN) and wikidata_id are useful for cross-referencing other sources.
Inputs: id (required), response_format. Returns: record, source
whitney_get_artworkGet a Whitney artworkARead-onlyIdempotent
Fetch one artwork's full record by ID.
Args:
id (string): the artwork's TMS ID, as returned by whitney_search_artworks
response_format ('markdown' | 'json', default 'markdown')
Returns: { record: { id, title, artist, artist_ids[], date, medium, dimensions, classification, department, accession_number, credit_line, on_view, description, object_label, visual_description, alt_text, images[], page_url } }
Fields are omitted when empty. Alt text is human-written where available and AI-generated otherwise; alt_text_is_ai_generated flags which.
Errors: returns a 404 message if the ID does not exist.
Inputs: id (required), response_format. Returns: record, source
whitney_get_exhibitionGet a Whitney exhibitionARead-onlyIdempotent
Fetch one exhibition record by ID.
Args:
id (string): exhibition ID, as returned by whitney_search_exhibitions
response_format ('markdown' | 'json', default 'markdown')
Returns: { record: {...} } — fields as published by the API, HTML stripped.
Inputs: id (required), response_format. Returns: record, source
whitney_queryRaw Whitney API queryARead-onlyIdempotent
Escape hatch for queries the typed tools do not cover. Hits any endpoint with arbitrary Ransack predicates.
Args:
endpoint ('artists' | 'artworks' | 'exhibitions' | 'events' | 'guides' | 'pages')
id (string, optional): fetch a single record instead of a list
filters (object, optional): raw predicates, e.g. { "medium_cont_all_split": "graphite paper" }
sort (string, optional): e.g. 'popularity desc'
page (number, default 1), limit (number, 1-30, default 10)
response_format ('markdown' | 'json', default 'markdown')
Returns: a list result, or { record: {...} } when 'id' is supplied.
Prefer the typed tools where they fit — they return tidier records. Use this to discover field names, combine unusual predicates, or reach the 'pages' endpoint. Note that 'pages' mirrors the Museum's CMS structure and is rarely useful outside it.
Inputs: endpoint (required), id, page, sort, +3 more.
whitney_search_artistsSearch Whitney artistsARead-onlyIdempotent
Search the 7,000+ artists listed by the Whitney — those with work in the collection and those who have appeared in Museum exhibitions.
Returns slim records (id, name, dates, in_collection, in_biennial, on_view). Call whitney_get_artist for the biography and authority IDs.
Args:
name (string, optional): substring match on the display name
in_collection, in_biennial, on_view (boolean, optional)
sort ('default' | 'name_asc' | 'name_desc' | 'most_viewed' | 'random')
page (number, default 1), limit (number, 1-30, default 10)
response_format ('markdown' | 'json', default 'markdown')
Returns: { total, count, page, has_more, next_page?, results[], note? }
Example: "which O'Keeffes are in the collection?" -> search name="O'Keeffe", then whitney_artist_artworks with the returned id.
Inputs: name, page, sort, limit, +4 more. Returns: note, page, count, total, +4 more
whitney_search_artworksSearch Whitney artworksARead-onlyIdempotent
Search the Whitney Museum's online collection of 27,000+ works.
Returns slim records (id, title, artist, date, medium, classification, on view, first image URL). Call whitney_get_artwork for the full record including dimensions, credit line, description and all images.
Args:
title, artist, medium, date (string, optional): substring matches
classification (string, optional): exact match, e.g. "Drawings"
department ('collection' | 'artport' | 'special', optional)
on_view (boolean, optional)
sort ('default' | 'title_asc' | 'title_desc' | 'most_viewed' | 'random')
page (number, default 1), limit (number, 1-30, default 10)
response_format ('markdown' | 'json', default 'markdown')
Returns: { total, count, page, has_more, next_page?, results[], note? }
Examples:
"watercolours with flowers in the title" -> title="flower", classification="Drawings", medium="watercolor"
"show me something at random from the collection" -> sort="random", limit=3
Notes:
Medium spellings follow US usage ("watercolor", "color").
Date is free text ("1915-1931, printed 1976-1977"), so filter loosely and check results.
Inputs: date, page, sort, limit, +7 more. Returns: note, page, count, total, +4 more
whitney_search_eventsSearch Whitney eventsARead-onlyIdempotent
Search Museum events — talks, tours, public programmes and so on — going back to 2008. This list is largely comprehensive.
Args:
title (string, optional): substring match
filters (object, optional): raw Ransack predicates
sort (string, optional): e.g. 'start_time desc'
starts_on_or_after / starts_on_or_before (string, optional): ISO dates (YYYY-MM-DD) filtering on start_time
page (number, default 1), limit (number, 1-30, default 10)
response_format ('markdown' | 'json', default 'markdown')
Returns: { total, count, page, has_more, next_page?, results[] }
As with exhibitions, fields are passed through generically. Sort by 'start_time desc' for the most recent programming.
Inputs: page, sort, limit, title, +4 more. Returns: note, page, count, total, +4 more
whitney_search_exhibitionsSearch Whitney exhibitionsARead-onlyIdempotent
Search exhibitions mounted by the Whitney, going back to 1931. Records are fuller for recent decades and sparse for the Museum's early history.
Args:
title (string, optional): substring match
filters (object, optional): raw Ransack predicates for fields this tool does not expose
sort (string, optional): e.g. 'start_time desc', 'random'
starts_on_or_after / starts_on_or_before (string, optional): ISO dates (YYYY-MM-DD) filtering on start_time
page (number, default 1), limit (number, 1-30, default 10)
response_format ('markdown' | 'json', default 'markdown')
Returns: { total, count, page, has_more, next_page?, results[] }
Exhibition fields are passed through generically — the Museum documents its field set as subject to change, so this tool keeps whatever scalar fields the API returns, strips HTML, shortens timestamps to dates and drops internal IDs. Known fields include title, start_time, end_time, date_override, url, primary_text, press_highlights and popularity. Run one search with limit=1 to confirm before writing a 'filters' query.
Inputs: page, sort, limit, title, +4 more. Returns: note, page, count, total, +4 more
whitney_search_guidesSearch Whitney audio guidesARead-onlyIdempotent
Search audio guides published since 2009. Fetching an individual guide also returns its stops.
Args:
title (string, optional), filters (object, optional), sort (string, optional)
page (number, default 1), limit (number, 1-30, default 10)
response_format ('markdown' | 'json', default 'markdown')
Returns: { total, count, page, has_more, next_page?, results[] }
Inputs: page, sort, limit, title, +2 more. Returns: note, page, count, total, +4 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each resource has a clear search/get or relationship tool, and the overlap between whitney_artist_artworks and whitney_search_artworks is explicitly resolved in the descriptions. whitney_query is positioned as an escape hatch for unsupported queries, not as a competing primary tool.
The whitney_ prefix with search_/get_ resource names forms a clear pattern for most tools. The exceptions are whitney_artist_artworks and whitney_artist_exhibitions, which use a possessive noun style rather than a verb_noun style, and whitney_query, which is a one-off.
11 tools is well-scoped for a museum API covering artists, artworks, exhibitions, events, and guides, plus relationship helpers and a query escape hatch. Each tool has a distinct job and none feel redundant.
Core read-only workflows are covered: search and detail retrieval exist for artworks, artists, and exhibitions, and searches exist for events and guides. The main gap is the lack of typed getters for individual events and guides, which the guide description implies should exist; whitney_query can work around this but it is less discoverable.
Maintenance
Related MCP Connectors
Art Institute of Chicago MCP — wraps the ARTIC public API (free, no auth)
Victoria and Albert Museum (V&A) Collections MCP. Keyless. Wraps the V&A Collections API v2.
Unlock a world of art with the Met Museum MCP! Use the 'search_artworks' API to find stunning
Search and manage your team's knowledge from MCP clients.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceInteract with the Cooper Hewitt API with MCP.2MIT
- AlicenseNot gradedqualityDmaintenanceProvides structured access to Wikipedia content including search, summaries, images, links, and more via MCP tools.6Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables searching and retrieving details from the Harvard Art Museums collection.79 npm2MIT
- AlicenseNot gradedqualityCmaintenanceEnables searching the Metropolitan Museum of Art collection by subject, artist, or keyword, retrieving detailed artwork information, and listing curatorial departments via natural language.72 npm3MIT