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框架
• 模型上下文協議社區