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
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:
# 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
The enhanced setup script now includes:
chmod +x config/setup.sh
config/setup.sh
Windows:
config\setup.ps1
uv pip install -r config/requirements.txt.env.example to .env and set your API keypython examples/test-api-connection.pyRun the verification script to check your installation:
python scripts/verify-setup.py
search_and_get_first_url() for one-step search + validated URL retrievalget_object_url() tool for any URL retrieval - manual construction fails due to case sensitivityclaude_desktop_config.json):{
"mcpServers": {
"smithsonian_open_access": {
"command": "npx",
"args": ["-y", "@molanojustin/smithsonian-mcp"],
"env": {
"SMITHSONIAN_API_KEY": "your_key_here"
}
}
}
}
claude_desktop_config.json):{
"mcpServers": {
"smithsonian_open_access": {
"command": "python",
"args": ["-m", "smithsonian_mcp.server"],
"env": {
"SMITHSONIAN_API_KEY": "your_key_here"
}
}
}
}
mcpo is an MCP orchestrator that converts multiple MCP servers into OpenAPI/HTTP endpoints, ideal for combining multiple services into a single systemd service.
# Install mcpo
uvx mcpo
# Or using uvx
uvx mcpo --help
Create a examples/mcpo-config.json file:
{
"mcpServers": {
"smithsonian_open_access": {
"command": "python",
"args": ["-m", "smithsonian_mcp.main"],
"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"]
}
}
}
# 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
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
See TROUBLESHOOTING.md for detailed mcpo troubleshooting, including:
code .vscode/smithsonian-mcp-workspace.code-workspaceCollection statistics for objects with images use sampling methodology to provide accurate estimates:
This approach ensures reliable metrics while respecting API rate limits and avoiding the Smithsonian API's rowCount filtering bug.
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.
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.
get_museum_collection_types, check_museum_has_object_type) to explore available collectionssimple_explore - Smart diverse sampling across museums and object types (recommended for general discovery)continue_explore - Get more results about the same topic while avoiding duplicatessearch_collections - Advanced search with filters (prioritizes museum-specific results when unit_code specified)search_and_get_first_url - Easiest option: Search and get validated URL in one step (prevents manual URL construction)get_object_details - Detailed object informationget_object_url - Get validated object URLs with flexible identifier support (MANDATORY: never construct URLs manually)search_by_unit - Museum-specific searchesget_objects_on_view - Find objects currently on physical exhibitcheck_object_on_view - Check if a specific object is on displayget_museum_collection_types - Get comprehensive list of object types available in each museum (based on systematic collection sampling)check_museum_has_object_type - Check if a specific museum has objects of a particular type (e.g., paintings, sculptures)get_smithsonian_units - List all museumsget_collection_statistics - Collection metrics with per-museum breakdownsget_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 (includes sampling-based estimates)get_on_view_context - Get currently exhibited objects as context# Test API connection
smithsonian-mcp --test
# Run MCP server
smithsonian-mcp
# Show help
smithsonian-mcp --help
# 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
# 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
# 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
# Start service
Start-Service SmithsonianMCP
# Stop service
Stop-Service SmithsonianMCP
# Check status
Get-Service SmithsonianMCP
For detailed troubleshooting guidance, including:
Please refer to TROUBLESHOOTING.md.
examples/ directoryscripts/ directoryMIT License - see LICENSE file for details.
Install via CLI
npx mdskills install molanojustin/smithsonian-mcpSmithsonian Open Access MCP Server is a free, open-source AI agent skill. 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
Install Smithsonian Open Access MCP Server with a single command:
npx mdskills install molanojustin/smithsonian-mcpThis downloads the skill files into your project and your AI agent picks them up automatically.
Smithsonian Open Access MCP Server works with Claude Code, Claude Desktop, Cursor, Vscode Copilot, Windsurf, Continue Dev, Gemini Cli, Amp, Roo Code, Goose. Skills use the open SKILL.md format which is compatible with any AI coding agent that reads markdown instructions.