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. The npm package includes automatic Python dependency management and works across platforms: The enhanced setup script
Add this skill
npx mdskills install molanojustin/smithsonian-mcpComprehensive MCP server providing well-documented access to 3M+ Smithsonian objects with 16 specialized tools
1# Smithsonian Open Access MCP Server23[](https://badge.fury.io/js/%40molanojustin%2Fsmithsonian-mcp)4[](https://www.npmjs.com/package/@molanojustin%2Fsmithsonian-mcp)5[](https://hub.docker.com/r/justinmol/smithsonian-mcp)67A **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.89## Quick Start1011### Option 1: npm/npx Installation (Easiest)1213The npm package includes automatic Python dependency management and works across platforms:1415```bash16# Install globally17npm install -g @molanojustin/smithsonian-mcp1819# Or run directly with npx (no installation needed)20npx -y @molanojustin/smithsonian-mcp2122# Set your API key23export SMITHSONIAN_API_KEY=your_key_here2425# Start the server26smithsonian-mcp27```2829### Option 2: Automated Setup (Recommended for Python users)3031The enhanced setup script now includes:3233- ✅ **API key validation** - Tests your key before saving34- ✅ **Service installation** - Auto-install as system service35- ✅ **Claude Desktop config** - Automatic configuration36- ✅ **Health checks** - Verify everything works37**macOS/Linux:**3839```bash40chmod +x config/setup.sh41config/setup.sh42```4344**Windows:**4546```powershell47config\setup.ps148```4950### Option 3: Manual Setup51521. **Get API Key**: [api.data.gov/signup](https://api.data.gov/signup/) (free)532. **Install**: `uv pip install -r config/requirements.txt`543. **Configure**: Copy `.env.example` to `.env` and set your API key554. **Test**: `python examples/test-api-connection.py`5657### Verify Setup5859Run the verification script to check your installation:6061```bash62python scripts/verify-setup.py63```6465## Features6667### Core Functionality6869- **Search Collections**: 3+ million objects across 24 Smithsonian museums70- **Object Details**: Complete metadata, descriptions, and provenance71- **On-View Status** - Find objects currently on physical exhibit72- **Image Access**: High-resolution images (CC0 licensed when available)73- **Museum Information**: Browse all Smithsonian institutions74- **Collection Statistics**: Comprehensive metrics with per-museum breakdowns (sampling-based estimates)7576### AI Integration7778- **16 MCP Tools**: Smart discovery, comprehensive search, museum-specific queries, exhibition status, contextual data access, and proactive collection type discovery79- **Proactive Discovery**: New tools help AI assistants understand API scope and available object types before searching, preventing confusion about archival vs. museum materials80- **Smart Context**: Contextual data sources for AI assistants including enhanced statistics81- **Rich Metadata**: Complete object information and exhibition details82- **Exhibition Planning** - Tools to find and explore currently exhibited objects83- **Collection Analytics**: Per-museum statistics with sampling-based accuracy84- **Multi-Model Compatible**: Works well with both advanced and simpler AI models through simplified tool interfaces8586### URL Validation & Anti-Guessing87- **Easiest Solution**: Use `search_and_get_first_url()` for one-step search + validated URL retrieval88- **Mandatory Tool Usage**: LLM must use `get_object_url()` tool for any URL retrieval - manual construction fails due to case sensitivity89- **Flexible Identifiers**: Supports Accession Numbers (F1900.47), Record IDs (fsg_F1900.47), and Internal IDs (ld1-...)90- **URL Validation**: Automatically selects authoritative record_link over API identifiers, handles case sensitivity9192## Integration9394### Claude Desktop9596#### Option 1: Using npm/npx (Recommended)97981. **Configure** (`claude_desktop_config.json`):99100```json101{102 "mcpServers": {103 "smithsonian_open_access": {104 "command": "npx",105 "args": ["-y", "@molanojustin/smithsonian-mcp"],106 "env": {107 "SMITHSONIAN_API_KEY": "your_key_here"108 }109 }110 }111}112```113114#### Option 2: Using Python installation1151161. **Configure** (`claude_desktop_config.json`):117118```json119{120 "mcpServers": {121 "smithsonian_open_access": {122 "command": "python",123 "args": ["-m", "smithsonian_mcp.server"],124 "env": {125 "SMITHSONIAN_API_KEY": "your_key_here"126 }127 }128 }129}130```1311322. **Test**: Ask Claude "What Smithsonian museums are available?"133134### mcpo Integration (MCP Orchestrator)135136**mcpo** is an MCP orchestrator that converts multiple MCP servers into OpenAPI/HTTP endpoints, ideal for combining multiple services into a single systemd service.137138#### Installation139140```bash141# Install mcpo142uvx mcpo143144# Or using uvx145uvx mcpo --help146```147148#### Configuration149150Create a `examples/mcpo-config.json` file:151152```json153{154 "mcpServers": {155 "smithsonian_open_access": {156 "command": "python",157 "args": ["-m", "smithsonian_mcp.main"],158 "env": {159 "SMITHSONIAN_API_KEY": "your_api_key_here"160 }161 },162 "memory": {163 "command": "npx",164 "args": ["-y", "@modelcontextprotocol/server-memory"]165 },166 "time": {167 "command": "uvx",168 "args": ["mcp-server-time", "--local-timezone=America/New_York"]169 }170 }171}172```173174#### Running with mcpo175176```bash177# Start mcpo with hot-reload178mcpo --config examples/mcpo-config.json --port 8000 --hot-reload179180# With API key authentication181mcpo --config examples/mcpo-config.json --port 8000 --api-key "your_secret_key"182183# Access endpoints:184# - Smithsonian: http://localhost:8000/smithsonian_open_access185# - Memory: http://localhost:8000/memory186# - Time: http://localhost:8000/time187# - API docs: http://localhost:8000/docs188```189190#### Systemd Service191192Create `/etc/systemd/system/mcpo.service`:193194```ini195[Unit]196Description=MCP Orchestrator Service197After=network.target198199[Service]200Type=simple201User=your-user202WorkingDirectory=/path/to/your/config203Environment=PATH=/path/to/venv/bin204ExecStart=/path/to/venv/bin/mcpo --config examples/mcpo-config.json --port 8000205Restart=always206RestartSec=10207208[Install]209WantedBy=multi-user.target210```211212```bash213# Enable and start service214sudo systemctl enable mcpo215sudo systemctl start mcpo216sudo systemctl status mcpo217```218219#### Troubleshooting mcpo220221See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed mcpo troubleshooting, including:222- ModuleNotFoundError solutions223- Connection closed errors224- Port conflicts225- Path configuration issues226227### VS Code2282291. **Open Workspace**: `code .vscode/smithsonian-mcp-workspace.code-workspace`2302. **Run Tasks**: Debug, test, and develop the MCP server2313. **Claude Code**: AI-assisted development with Smithsonian data232233## Available Data234235- **19 Museums**: NMNH, NPG, SAAM, NASM, NMAH, and more236- **3+ Million Objects**: Digitized collection items237- **CC0 Content**: Public domain materials for commercial use238- **Rich Metadata**: Creators, dates, materials, dimensions239- **High-Resolution Images**: Professional photography240241### Data Accuracy & Sampling242243Collection statistics for objects with images use **sampling methodology** to provide accurate estimates:244245- **Sample Size**: Up to 1000 objects per query for statistical significance246- **Methodology**: Counts actual returned objects instead of relying on potentially buggy API totals247- **Coverage**: Includes per-museum breakdowns with individual sampling for each institution248- **Transparency**: All sampled counts are clearly marked as "(est.)" in outputs249250This approach ensures reliable metrics while respecting API rate limits and avoiding the Smithsonian API's rowCount filtering bug.251252### Current API Limitations253254**Image URLs Not Available**: The Smithsonian Open Access API currently does not provide image URLs or media data in detailed content responses. While the search API can filter objects by media type (e.g., `online_media_type:Images`), the actual image URLs are not included in the detailed object data returned by the content API. This appears to be a change in the API since the available documentation was published.255256- Objects will show as having 0 images even when filtered for image content257- Image statistics are estimates based on search filtering, not actual media availability258- The system gracefully handles this limitation and continues to provide all other metadata259260**API Scope: Diverse Museum Collections**: The Smithsonian Open Access API provides access to diverse collections across 24 Smithsonian museums, with each museum having distinct object types reflecting their unique focus areas. The discovery tools now correctly identify museum-specific collections with comprehensive object type intelligence gathered through systematic sampling.261262- **SAAM** (American Art): Paintings, decorative arts, sculptures, drawings263- **NASM** (Air & Space): Aircraft, avionics, spacecraft, aviation equipment264- **NMAH** (American History): Historical artifacts, inventions, cultural objects265- **CHNDM** (Design Museum): Design objects, textiles, furniture, graphics266- Use discovery tools (`get_museum_collection_types`, `check_museum_has_object_type`) to explore available collections267- Each museum's collection reflects its institutional mission and expertise268269## MCP Tools270271### Search & Discovery272273- `simple_explore` - Smart diverse sampling across museums and object types (recommended for general discovery)274- `continue_explore` - Get more results about the same topic while avoiding duplicates275- `search_collections` - Advanced search with filters (prioritizes museum-specific results when unit_code specified)276- `search_and_get_first_url` - **Easiest option**: Search and get validated URL in one step (prevents manual URL construction)277- `get_object_details` - Detailed object information278- `get_object_url` - Get validated object URLs with flexible identifier support (MANDATORY: never construct URLs manually)279- `search_by_unit` - Museum-specific searches280- `get_objects_on_view` - Find objects currently on physical exhibit281- `check_object_on_view` - Check if a specific object is on display282- `get_museum_collection_types` - Get comprehensive list of object types available in each museum (based on systematic collection sampling)283- `check_museum_has_object_type` - Check if a specific museum has objects of a particular type (e.g., paintings, sculptures)284285### Information & Context286287- `get_smithsonian_units` - List all museums288- `get_collection_statistics` - Collection metrics with per-museum breakdowns289- `get_search_context` - Get search results as context data290- `get_object_context` - Get detailed object information as context291- `get_units_context` - Get list of units as context data292- `get_stats_context` - Get collection statistics as context (includes sampling-based estimates)293- `get_on_view_context` - Get currently exhibited objects as context294295## Use Cases296297### Research & Education298299- **Scholarly Research**: Multi-step academic investigation300- **Lesson Planning**: Educational content creation301- **Object Analysis**: In-depth cultural object study302- **URL Retrieval**: Get validated object web page URLs (with anti-guessing protection)303304### Curation & Exhibition305306- **Exhibition Planning**: Thematic object selection and visitor planning307- **Visit Planning**: Find what's currently on display before visiting308- **Exhibition Research**: Study current exhibition trends and displays309- **Collection Development**: Gap analysis and acquisition310- **Digital Humanities**: Large-scale analysis projects311312### Development313314- **Cultural Apps**: Applications using museum data315- **Educational Tools**: Interactive learning platforms316- **API Integration**: Professional development workflows317318## Requirements319320### For npm/npx installation:321322- Node.js 16.0 or higher323- Python 3.10 or higher (auto-detected and dependencies managed)324- API key from [api.data.gov](https://api.data.gov/signup/) (free)325- Internet connection for API access326327### For Python installation:328329- Python 3.10 or higher330- API key from [api.data.gov](https://api.data.gov/signup/) (free)331- Internet connection for API access332333## Testing334335### Using npm/npx:336337```bash338# Test API connection339smithsonian-mcp --test340341# Run MCP server342smithsonian-mcp343344# Show help345smithsonian-mcp --help346```347348### Using Python:349350```bash351# Test API connection352python examples/test-api-connection.py353354# Run MCP server355python -m smithsonian_mcp.server356357# Run test suite358pytest tests/359360# Run on-view functionality tests361pytest tests/test_on_view.py -v362363# Run basic tests364pytest tests/test_basic.py -v365366# Verify complete setup367python scripts/verify-setup.py368369# VS Code Tasks (if using workspace)370# - Test MCP Server371# - Run Tests372# - Format Code373# - Lint Code374```375376## Service Management377378### Linux (systemd)379380```bash381# Start service382systemctl --user start smithsonian-mcp383384# Stop service385systemctl --user stop smithsonian-mcp386387# Check status388systemctl --user status smithsonian-mcp389390# Enable on boot391systemctl --user enable smithsonian-mcp392```393394### macOS (launchd)395396```bash397# Load service398launchctl load ~/Library/LaunchAgents/com.smithsonian.mcp.plist399400# Unload service401launchctl unload ~/Library/LaunchAgents/com.smithsonian.mcp.plist402403# Check status404launchctl list | grep com.smithsonian.mcp405```406407### Windows408409```powershell410# Start service411Start-Service SmithsonianMCP412413# Stop service414Stop-Service SmithsonianMCP415416# Check status417Get-Service SmithsonianMCP418```419420## Troubleshooting421422For detailed troubleshooting guidance, including:423- Common setup issues424- Service startup problems425- API key validation426- Claude Desktop connection issues427- Module import errors428- Platform-specific problems429430Please refer to [TROUBLESHOOTING.md](TROUBLESHOOTING.md).431432## Documentation433434### Available Documentation435436- **[README.md](README.md)** - Main setup and usage guide (this file)437- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Comprehensive troubleshooting and common issues438- **Examples** - Real-world usage scenarios in `examples/` directory439- **Scripts** - Setup and utility scripts in `scripts/` directory440441### Key Reference442- **API Reference**: Complete tool and resource documentation in this README443- **Deployment Guide**: Production deployment options included in setup instructions444- **Integration Guide**: Claude Desktop and mcpo setup instructions in this README445446## Contributing4474481. Fork the repository4492. Create a feature branch4503. Make your changes4514. Run tests4525. Submit a pull request453454## License455456MIT License - see LICENSE file for details.457458## Acknowledgments459460- **Smithsonian Institution** for Open Access collections461- **api.data.gov** for API infrastructure462- **FastMCP** team for the MCP framework463- **Model Context Protocol** community464
Full transparency — inspect the skill content before installing.