smithsonian-mcp

🚀 史密森尼开放获取MCP服务器

史密森尼开放获取MCP服务器是一个模型上下文协议（MCP） 服务器，它为AI助手提供访问史密森尼学会开放获取藏品的途径。借助该服务器，像Claude Desktop这样的AI工具能够搜索、探索和分析来自美国国家博物馆的300多万件藏品。

🚀 快速开始

选项1：npm/npx安装（最简单）

npm包包含自动Python依赖管理功能，且跨平台可用：

# 全局安装
npm install -g @molanojustin/smithsonian-mcp

# 或者直接使用npx运行（无需安装）
npx -y @molanojustin/smithsonian-mcp

# 设置API密钥
export SMITHSONIAN_API_KEY=your_key_here

# 启动服务器
smithsonian-mcp

选项2：自动设置（推荐Python用户）

增强版的设置脚本具备以下功能：

• ✅ API密钥验证 - 在保存前测试密钥
• ✅ 服务安装 - 自动作为系统服务安装
• ✅ Claude Desktop配置 - 自动配置
• ✅ 健康检查 - 验证一切是否正常工作

macOS/Linux：

chmod +x setup.sh
./setup.sh

Windows：

.\setup.ps1

选项3：手动设置

1. 获取API密钥：api.data.gov/signup（免费）
2. 安装：pip install -r requirements.txt
3. 配置：将.env.example复制为.env并设置API密钥
4. 测试：python examples/test-api-connection.py

验证设置

运行验证脚本来检查安装情况：

python scripts/verify-setup.py

✨ 主要特性

核心功能

• 搜索藏品：可搜索19家史密森尼博物馆的300多万件藏品
• 物品详情：提供完整的元数据、描述和出处信息
• 展出状态：⭐ 新增 - 查找当前正在实体展览中展出的物品
• 图像访问：可获取高分辨率图像（如有CC0许可）
• 3D模型：在有可用资源的情况下，提供交互式3D内容
• 博物馆信息：浏览所有史密森尼学会的机构信息

AI集成

• 12个MCP工具：可用于搜索、过滤、检索藏品数据、检查展览状态和获取上下文信息
• 智能上下文：为AI助手提供上下文数据源
• 丰富的元数据：包含完整的物品信息和展览详情
• 展览规划：⭐ 新增 - 提供查找和探索当前展出物品的工具

📦 安装指南

npm/npx安装要求

• Node.js 16.0或更高版本
• Python 3.10或更高版本（自动检测并管理依赖）
• 从api.data.gov获取的API密钥（免费）
• 用于访问API的互联网连接

Python安装要求

• Python 3.10或更高版本
• 从api.data.gov获取的API密钥（免费）
• 用于访问API的互联网连接

💻 使用示例

基础用法

在Claude中询问：

# 查找所有当前正在展出的物品
"What objects are currently on physical exhibit at the Smithsonian?"

# 或者带过滤条件
"Show me paintings currently on display at the National Portrait Gallery"

高级用法

# 检查特定物品是否正在展出
"Is object edanmdm-nmah_1234567 currently on display?"

# 结合其他过滤条件
"Find CC0 licensed objects currently on view with high-resolution images"

📚 详细文档

集成指南

包含Claude Desktop和VS Code的设置说明。

API参考

提供完整的工具和资源文档。

示例

展示真实世界的使用场景。

部署指南

介绍生产环境的部署选项。

🔧 技术细节

新的展出功能

MCP服务器现在全面支持查找史密森尼博物馆当前正在实体展览中展出的物品，这是一项优先功能，与史密森尼官方API文档保持一致。

关键特性

• 查找展出物品：搜索当前正在展出的物品
• 检查展览状态：验证特定物品是否正在展出
• 按博物馆过滤：查找特定史密森尼机构正在展出的物品
• 展览详情：访问展览标题和位置信息
• 组合过滤：将展出状态与其他搜索条件结合使用

工具详情

get_objects_on_view

查找当前正在实体展览中展出的物品。

参数：

• unit_code（可选）：按史密森尼机构代码过滤（例如，"NMNH"，"NPG"）
• limit：最大结果数（默认：20，最大：100）
• offset：分页偏移量

返回： 包含当前正在展出物品的搜索结果

check_object_on_view

检查特定物品是否当前正在展出。

参数：

• object_id：物品的唯一标识符

返回： 包含展览状态的物品详情

search_collections（增强版）

现在包含on_view参数用于过滤。

新增参数：

• on_view（布尔值）：按展览状态过滤物品
  • True：仅显示当前正在展出的物品
  • False：仅显示当前未展出的物品
  • None：不进行过滤（默认）

实现说明

此功能基于史密森尼的onPhysicalExhibit元数据字段，该字段指示物品是否当前在实体展览中对公众开放。实现包括：

• 与EDAN元数据模型v1.09完全对齐的API
• 使用onPhysicalExhibit:"Yes"查询的字段搜索支持
• 全面的测试覆盖（15个单元测试）
• 展览元数据提取（标题，位置）

📄 许可证

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

贡献说明

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 运行测试
5. 提交拉取请求

致谢

• 史密森尼学会 提供开放获取藏品
• api.data.gov 提供API基础设施
• FastMCP团队 提供MCP框架
• 模型上下文协议社区