Smithsonian Open Access

You can run a dedicated MCP server that gives AI assistants access to Smithsonian Open Access collections, enabling smart search, object detail retrieval, exhibition status checks, and rich contextual data across millions of items from 24 Smithsonian museums.

How to use

Use an MCP client (such as Claude Desktop or a dedicated MCP orchestrator) to connect to the Smithsonian Open Access MCP Server. You will be able to search across millions of objects, fetch detailed metadata, check which items are currently on view, and access contextual data to support research, education, and exhibition planning. The server exposes a set of MCP tools that you can invoke with simple interfaces, and it supports both single-server usage and multi-server orchestration through an MCP orchestrator.

How to install

Prerequisites you need to prepare before starting: Node.js 16.0 or higher, Python 3.10 or higher, and an API key from api.data.gov (free). Ensure you have internet access to fetch data from Smithsonian Open Access.

Option A: npm/npx installation (easiest) covers automatic Python dependency management and works across platforms.

Option B: Automated setup for Python users provides API key validation, service installation, Claude Desktop configuration, and health checks.

Option C: Manual setup lets you configure the environment yourself and run a test to verify connectivity.

# Option A: npm/npx installation
# 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 B: Automated setup (macOS/Linux)
chmod +x config/setup.sh
config/setup.sh

# Option B: Automated setup (Windows)
config\setup.ps1

# Option C: Manual setup
# 1. Get API Key
# 2. Install dependencies
uv pip install -r config/requirements.txt

# 3. Configure
cp .env.example .env
# Set your API key in .env

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

Additional setup and verification

Verify the complete setup by running the verification script to confirm the server is reachable and authenticated.

python scripts/verify-setup.py

Configuration and orchestration notes

The server can be configured for direct usage or combined with an MCP orchestrator to expose multiple MCP servers as OpenAPI/HTTP endpoints. The configuration examples below show how to set up the Smithsonian Open Access MCP Server for both direct usage and orchestration.

Data and capabilities overview

Core functionality includes search across 3+ million objects, detailed object metadata and provenance, on-view status checks, high-resolution images where available, and comprehensive museum information with per-museum statistics. Tools support discovery, object retrieval, type checks, and context data generation to aid AI-assisted exploration and analysis.

Security and keys

Protect your API key and avoid exposing it in client-side configurations. Use environment variables to inject the key into your MCP server process and never commit sensitive values to version control.

Troubleshooting and notes

If you encounter issues starting services, verify the environment, ensure the API key is valid, and check network connectivity to the Smithsonian API. For orchestrated setups, confirm that each configured server has a valid command and arguments, and review any error logs from the orchestrator for module import or connection problems.

Example MCP server configurations

Use the following configurations to run the Smithsonian Open Access MCP Server in different environments. The entries include both the direct npm/npx option and the Python-based option for running as a local MCP server.

Examples

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

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

Available Data

• 19 Museums covered including NMNH, NPG, SAAM, NASM, NMAH, and others
• 3+ Million objects in the collection
• CC0 content available where possible
• Rich metadata including creators, dates, materials, and dimensions
• High-resolution images where accessible and permitted

Available tools

simple_explore

Smart discovery across museums with diverse sampling to identify relevant objects and trends.

continue_explore

Retrieve more results on the same topic while avoiding duplicates.

search_collections

Advanced search with filters, prioritizing museum-specific results when a unit_code is specified.

search_and_get_first_url

Easiest option to search and obtain a validated object URL in one step.

get_object_details

Fetch detailed information about a specific object.

get_object_url

Get a validated object URL using flexible identifiers; manual URL construction is discouraged.

search_by_unit

Perform searches scoped to a specific museum unit.

get_objects_on_view

Find objects currently exhibited in museums.

check_object_on_view

Check if a specific object is on display.

get_museum_collection_types

Obtain comprehensive lists of object types available by museum.

check_museum_has_object_type

Check if a museum has objects of a particular type (e.g., paintings).

get_smithsonian_units

List all participating Smithsonian museums.

get_collection_statistics

Provide per-museum collection metrics with sampling-based estimates.

get_search_context

Get search results formatted as context data for AI use.

get_object_context

Get detailed object information formatted as context data.

get_units_context

Provide museum unit information as context data.

get_stats_context

Provide collection statistics as context with sampling estimates.

get_on_view_context

Get currently exhibited objects as context data.