Provides access to the Smithsonian Institution's Open Access collections with over 3 million digitized objects, allowing AI assistants to search collections, retrieve detailed object metadata, check exhibition status, and access high-resolution images and 3D models from 19 Smithsonian museums.
Smithsonian Open Access MCP Server
A Model Context Protocol (MCP) server that provides AI assistants with access to the Smithsonian Institution's Open Access collections. This server allows AI tools like Claude Desktop to search, explore, and analyze over 3 million collection objects from America's national museums.
Quick Start
Option 1: npm/npx Installation (Easiest)
The npm package includes automatic Python dependency management and works across platforms:
Option 2: Automated Setup (Recommended for Python users)
The enhanced setup script now includes:
✅ API key validation - Tests your key before saving
✅ Service installation - Auto-install as system service
✅ Claude Desktop config - Automatic configuration
✅ Health checks - Verify everything works macOS/Linux:
Windows:
Option 3: Manual Setup
Get API Key: api.data.gov/signup (free)
Install:
pip install -r requirements.txt
Configure: Copy
.env.example
to.env
and set your API keyTest:
python examples/test-api-connection.py
Verify Setup
Run the verification script to check your installation:
Features
Core Functionality
Search Collections: 3+ million objects across 19 Smithsonian museums
Object Details: Complete metadata, descriptions, and provenance
On-View Status: ⭐ NEW - Find objects currently on physical exhibit
Image Access: High-resolution images (CC0 licensed when available)
3D Models: Interactive 3D content where available
Museum Information: Browse all Smithsonian institutions
AI Integration
12 MCP Tools: Search, filter, retrieve collection data, check exhibition status, and get context
Smart Context: Contextual data sources for AI assistants
Rich Metadata: Complete object information and exhibition details
Exhibition Planning: ⭐ NEW - Tools to find and explore currently exhibited objects
Integration
Claude Desktop
Option 1: Using npm/npx (Recommended)
Configure (
claude_desktop_config.json
):
Option 2: Using Python installation
Configure (
claude_desktop_config.json
):
Or copy the provided
Test: Ask Claude "What Smithsonian museums are available?"
mcpo Integration (MCP Orchestrator)
mcpo is an MCP orchestrator that converts multiple MCP servers into OpenAPI/HTTP endpoints, ideal for combining multiple services into a single systemd service.
Installation
Configuration
Create a mcpo-config.json
file:
Running with mcpo
Systemd Service
Create /etc/systemd/system/mcpo.service
:
Troubleshooting mcpo
"ModuleNotFoundError: No module named 'smithsonian_mcp'" This occurs when mcpo can't find the Smithsonian MCP module. Fix by:
Use absolute Python path in your mcpo config:
Verify paths:
Regenerate config with setup script:
"Connection closed" errors
Ensure API key is valid and set in environment
Check that the virtual environment has all dependencies installed
Verify the MCP server can start manually:
python -m smithsonian_mcp.server --test
"Port 8000 already in use"
VS Code
Open Workspace:
code .vscode/smithsonian-mcp-workspace.code-workspace
Run Tasks: Debug, test, and develop the MCP server
Claude Code: AI-assisted development with Smithsonian data
Available Data
19 Museums: NMNH, NPG, SAAM, NASM, NMAH, and more
3+ Million Objects: Digitized collection items
CC0 Content: Public domain materials for commercial use
Rich Metadata: Creators, dates, materials, dimensions
High-Resolution Images: Professional photography
3D Models: Interactive digital assets
MCP Tools
Search & Discovery
search_collections
- Advanced search with filters (now includeson_view
parameter)get_object_details
- Detailed object informationsearch_by_unit
- Museum-specific searches⭐
get_objects_on_view
- NEW - Find objects currently on physical exhibit⭐
check_object_on_view
- NEW - Check if a specific object is on display
Information & Context
get_smithsonian_units
- List all museumsget_collection_statistics
- Collection metricsget_search_context
- Get search results as context dataget_object_context
- Get detailed object information as contextget_units_context
- Get list of units as context dataget_stats_context
- Get collection statistics as context⭐
get_on_view_context
- NEW - Get currently exhibited objects as context
New: On-View Functionality 🎨
What's New in Phase 1
The MCP server now includes comprehensive support for finding objects currently on physical exhibit at Smithsonian museums. This is a priority feature aligned with the Smithsonian's official API documentation.
Key Features
Find Exhibited Objects: Search for objects currently on display
Check Exhibition Status: Verify if specific objects are on view
Filter by Museum: Find what's on display at specific Smithsonian units
Exhibition Details: Access exhibition title and location information
Combined Filters: Mix on-view status with other search criteria
Usage Examples
Find all objects currently on view:
Check if a specific object is on view:
Combine with other filters:
Tool Details
get_objects_on_view
Find objects currently on physical exhibit.
Parameters:
unit_code
(optional): Filter by Smithsonian unit (e.g., "NMNH", "NPG")limit
: Maximum results (default: 20, max: 100)offset
: Pagination offset
Returns: Search results containing objects currently on exhibit
check_object_on_view
Check if a specific object is currently on display.
Parameters:
object_id
: Unique identifier for the object
Returns: Object details including exhibition status
search_collections
(enhanced)
Now includes on_view
parameter for filtering.
New Parameter:
on_view
(boolean): Filter objects by exhibition statusTrue
: Only objects currently on displayFalse
: Only objects not on displayNone
: No filter (default)
Implementation Notes
This feature is based on the Smithsonian's onPhysicalExhibit
metadata field, which indicates whether an object is currently accessible to the public in a physical exhibition. The implementation includes:
Full API alignment with EDAN metadata model v1.09
Fielded search support using
onPhysicalExhibit:"Yes"
queriesComprehensive test coverage (15 unit tests)
Exhibition metadata extraction (title, location)
Use Cases
Research & Education
Scholarly Research: Multi-step academic investigation
Lesson Planning: Educational content creation
Object Analysis: In-depth cultural object study
Curation & Exhibition
Exhibition Planning: Thematic object selection and visitor planning
Visit Planning: ⭐ NEW - Find what's currently on display before visiting
Exhibition Research: ⭐ NEW - Study current exhibition trends and displays
Collection Development: Gap analysis and acquisition
Digital Humanities: Large-scale analysis projects
Development
Cultural Apps: Applications using museum data
Educational Tools: Interactive learning platforms
API Integration: Professional development workflows
Requirements
For npm/npx installation:
Node.js 16.0 or higher
Python 3.10 or higher (auto-detected and dependencies managed)
API key from api.data.gov (free)
Internet connection for API access
For Python installation:
Python 3.10 or higher
API key from api.data.gov (free)
Internet connection for API access
Testing
Using npm/npx:
Using Python:
Service Management
Linux (systemd)
macOS (launchd)
Windows
Troubleshooting
Common Issues
"API key validation failed"
Get a free key from api.data.gov/signup
Ensure no extra spaces in your API key
Check that
.env
file contains:SMITHSONIAN_API_KEY=your_key_here
"Service failed to start"
Run
python scripts/verify-setup.py
for diagnosticsCheck logs:
journalctl --user -u smithsonian-mcp
(Linux) or~/Library/Logs/com.smithsonian.mcp.log
(macOS)Ensure virtual environment is activated
"Claude Desktop not connecting"
Restart Claude Desktop after configuration
Check Claude Desktop config file exists and contains correct paths
Verify MCP server is running:
python -m smithsonian_mcp.server
"Module import errors"
Activate virtual environment:
source .venv/bin/activate
(Linux/macOS) or.\venv\Scripts\Activate.ps1
(Windows)Reinstall dependencies:
pip install -r requirements.txt
Getting Help
Run verification script:
python scripts/verify-setup.py
Check the Integration Guide
Review GitHub Issues
Documentation
Integration Guide: Claude Desktop and VS Code setup
API Reference: Complete tool and resource documentation
Examples: Real-world usage scenarios
Deployment Guide: Production deployment options
Contributing
Fork the repository
Create a feature branch
Make your changes
Run tests
Submit a pull request
License
MIT License - see LICENSE file for details.
Acknowledgments
Smithsonian Institution for Open Access collections
api.data.gov for API infrastructure
FastMCP team for the MCP framework
Model Context Protocol community
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Provides AI assistants with access to search, explore, and analyze over 3 million collection objects from the Smithsonian Institution's museums. Enables finding objects currently on exhibit, retrieving detailed metadata, high-resolution images, and 3D models from America's national museums.