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:

# Install globally
npm install -g @molanojustin/smithsonian-mcp

# Or run directly with npx (no installation needed)
npx -y @molanojustin/smithsonian-mcp

# Set your API key
export SMITHSONIAN_API_KEY=your_key_here

# Start the server
smithsonian-mcp

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:

chmod +x config/setup.sh
config/setup.sh

Windows:

config\setup.ps1

Option 3: Manual Setup

Get API Key: api.data.gov/signup (free)
Install: uv pip install -r config/requirements.txt
Configure: Copy .env.example to .env and set your API key
Test: python examples/test-api-connection.py

Verify Setup

Run the verification script to check your installation:

python scripts/verify-setup.py

Features

Core Functionality

Search Collections: 3+ million objects across 19 Smithsonian museums
Object Details: Complete metadata, descriptions, and provenance
On-View Status - 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

14 MCP Tools: Smart discovery, comprehensive search, museum-specific queries, exhibition status, and contextual data access
Smart Context: Contextual data sources for AI assistants
Rich Metadata: Complete object information and exhibition details
Exhibition Planning - Tools to find and explore currently exhibited objects
Multi-Model Compatible: Works well with both advanced and simpler AI models through simplified tool interfaces

Integration

Claude Desktop

Option 1: Using npm/npx (Recommended)

Configure (claude_desktop_config.json):

{
  "mcpServers": {
    "smithsonian_open_access": {
      "command": "npx",
      "args": ["-y", "@molanojustin/smithsonian-mcp"],
      "env": {
        "SMITHSONIAN_API_KEY": "your_key_here"
      }
    }
  }
}

Option 2: Using Python installation

Configure (claude_desktop_config.json):

{
  "mcpServers": {
    "smithsonian_open_access": {
      "command": "python",
      "args": ["-m", "smithsonian_mcp.server"],
      "env": {
        "SMITHSONIAN_API_KEY": "your_key_here"
      }
    }
  }
}

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

# Install mcpo
uvx mcpo

# Or using uvx
uvx mcpo --help

Configuration

Create a examples/mcpo-config.json file:

{
  "mcpServers": {
    "smithsonian_open_access": {
      "command": "python",
      "args": ["-m", "smithsonian_mcp.server"],
      "env": {
        "SMITHSONIAN_API_KEY": "your_api_key_here"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=America/New_York"]
    }
  }
}

Running with mcpo

# Start mcpo with hot-reload
mcpo --config examples/mcpo-config.json --port 8000 --hot-reload

# With API key authentication
mcpo --config examples/mcpo-config.json --port 8000 --api-key "your_secret_key"

# Access endpoints:
# - Smithsonian: http://localhost:8000/smithsonian_open_access
# - Memory: http://localhost:8000/memory
# - Time: http://localhost:8000/time
# - API docs: http://localhost:8000/docs

Systemd Service

Create /etc/systemd/system/mcpo.service:

[Unit]
Description=MCP Orchestrator Service
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/your/config
Environment=PATH=/path/to/venv/bin
ExecStart=/path/to/venv/bin/mcpo --config examples/mcpo-config.json --port 8000
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# Enable and start service
sudo systemctl enable mcpo
sudo systemctl start mcpo
sudo systemctl status mcpo

Troubleshooting mcpo

See TROUBLESHOOTING.md for detailed mcpo troubleshooting, including:

ModuleNotFoundError solutions
Connection closed errors
Port conflicts
Path configuration issues

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

simple_explore - Smart diverse sampling across museums and object types (recommended for general discovery)
continue_explore - Get more results about the same topic while avoiding duplicates
search_collections - Advanced search with filters (now includes on_view parameter)
get_object_details - Detailed object information
search_by_unit - Museum-specific searches
get_objects_on_view - Find objects currently on physical exhibit
check_object_on_view - Check if a specific object is on display

Information & Context

get_smithsonian_units - List all museums
get_collection_statistics - Collection metrics
get_search_context - Get search results as context data
get_object_context - Get detailed object information as context
get_units_context - Get list of units as context data
get_stats_context - Get collection statistics as context
get_on_view_context - Get currently exhibited objects as context

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: Find what's currently on display before visiting
Exhibition Research: 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:

# Test API connection
smithsonian-mcp --test

# Run MCP server
smithsonian-mcp

# Show help
smithsonian-mcp --help

Using Python:

# Test API connection
python examples/test-api-connection.py

# Run MCP server
python -m smithsonian_mcp.server

# Run test suite
pytest tests/

# Run on-view functionality tests
pytest tests/test_on_view.py -v

# Run basic tests
pytest tests/test_basic.py -v

# Verify complete setup
python scripts/verify-setup.py

# VS Code Tasks (if using workspace)
# - Test MCP Server
# - Run Tests
# - Format Code
# - Lint Code

Service Management

Linux (systemd)

# Start service
systemctl --user start smithsonian-mcp

# Stop service
systemctl --user stop smithsonian-mcp

# Check status
systemctl --user status smithsonian-mcp

# Enable on boot
systemctl --user enable smithsonian-mcp

macOS (launchd)

# Load service
launchctl load ~/Library/LaunchAgents/com.smithsonian.mcp.plist

# Unload service
launchctl unload ~/Library/LaunchAgents/com.smithsonian.mcp.plist

# Check status
launchctl list | grep com.smithsonian.mcp

Windows

# Start service
Start-Service SmithsonianMCP

# Stop service
Stop-Service SmithsonianMCP

# Check status
Get-Service SmithsonianMCP

Troubleshooting

For detailed troubleshooting guidance, including:

Common setup issues
Service startup problems
API key validation
Claude Desktop connection issues
Module import errors
Platform-specific problems

Please refer to TROUBLESHOOTING.md.

Documentation

Available Documentation

README.md - Main setup and usage guide (this file)
TROUBLESHOOTING.md - Comprehensive troubleshooting and common issues
Examples - Real-world usage scenarios in examples/ directory
Scripts - Setup and utility scripts in scripts/ directory

Key Reference

API Reference: Complete tool and resource documentation in this README
Deployment Guide: Production deployment options included in setup instructions
Integration Guide: Claude Desktop and mcpo setup instructions in this README

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

Smithsonian Open Access