@cyanheads/smithsonian-mcp-server

Public Hosted Server: https://smithsonian.caseyjhand.com/mcp

Overview

The Smithsonian's Open Access catalog: 14.5 million objects across 20+ museums, 5.2 million with CC0 images. Search by free text or category, browse by museum, culture, date, or topic, and discover connections across collections.

Tools

Skill

Ships in skills/ for plugin installs, the npm package, the Docker image, and the .mcpb bundle, and is served over MCP as skill://smithsonian-guide/SKILL.md.

Related MCP server: archival-imagery-mcp

Capability reference

smithsonian_search_objects tool

• Free-text search over 14.5M objects from 20+ museums

• Filters append hard AND constraints. Plain words and quoted phrases keep their matching semantics; active Lucene expressions are grouped to preserve Boolean precedence.

• filters.online_media_type accepts exact smithsonian_list_terms media categories such as Images, 3D Models, and Sound recordings. These describe the index; even Images does not guarantee attached or CC0 images. Check smithsonian_get_object.media_summary for deliverability. Media categories feed search, with no media-type browse mode.

• Filters: museum unit code, object type, indexed date term (1920s, 500-1500, 21st century, -2500), culture, geographic place, subject topic, named party (name), scientific name (scientific_name), indexed media category (online_media_type), online-only, CC0-only

• topic and name are hard indexed constraints, not free text — topic: "Quilts" matches 1,134 objects where the bare word matches 2,677, and name: "Warhol, Andy" matches 421 against 715

• Returns curated summaries: title, date, museum, object type, thumbnail URL, CC0 flag, record_id, plus holding_museum_name when the holding unit differs from the indexed unit_code (the 3D digitization scans)

• An unknown filters key is rejected by name

• Use start + rows for standard pagination (offset-based, default 20, up to 1,000 per page — a larger rows is served at 1,000 with a notice). When objects remain, the notice names the next start

smithsonian_list_terms tool

• Fields: unit_code, culture, place, date, online_media_type, topic — a controlled vocabulary, often plural (e.g. Paintings, not Painting); ground filter values here before searching or browsing

• contains filters the vocabulary by a case-insensitive substring — resolves a guessed value (e.g. greek → Greek, Attic) in one call; for unit_code it also matches museum names (National Air and Space → NASM), and each unit_code term comes back with a labels map of its museum name

• Paginate with start + rows (default 50, up to 40,000 per page — a larger rows is served at 40,000 with a notice); topic (133k terms) and place (114k) are large enough to pair with contains

• No per-term object counts are available upstream — only the term values themselves

• Each field's vocabulary is cached for SMITHSONIAN_TERMS_CACHE_TTL_SECONDS (default 3600 seconds, 0 disables) — upstream ignores paging and returns the whole set on every call, so paging a large vocabulary uncached re-downloads it each time

• object_type is not enumerable here — harvest its values from the object_type field in smithsonian_search_objects results

smithsonian_get_object tool

• Input: record_id from smithsonian_search_objects — do not construct IDs manually

• Returns the exposed catalog fields: title, dates (all labeled), makers (with roles), materials, dimensions, place associations, culture terms, topic/subject terms, exhibition history, accession identifiers, credit line, rights statement

• Media summary included — call smithsonian_get_media for full image URLs. media_summary.non_image_media[] lists every media item that is not an image (3D models, scanned books, documents) as { type, url?, is_cc0 }, in catalog order

• holding_museum_name names the holding unit when it differs from unit_code, the code the record is indexed under (the 3D digitization scans); the text output renders it as Held by

• All nonempty notes retain their catalog labels and source order. description selects recognized prose labels; administrative notes stay labeled.

• Natural-history metadata includes all scientific_names, reported taxonomy ranks, and valid decimal collection coordinates with their own locality when present. The arrays are empty when no names or valid points are available; absent ranks are omitted. No accepted name, geocoding, or accuracy is inferred. Use scientific_names as exact filters.scientific_name values in search; this field is not enumerable via smithsonian_list_terms.

smithsonian_get_media tool

• Only CC0-licensed images are returned, never restricted content

• Three distinct failure reasons when nothing is returnable: no_media (nothing digitized), no_images (media exists but is entirely non-image — 3D models, scanned books, documents; the recovery hint names the types present and points to smithsonian_get_object's media_summary.non_image_media, which links each item), not_cc0 (images exist but none are CC0, thrown as Forbidden)

• Each image entry includes thumbnail (~120px), screen-size (~800px), and high-resolution JPEG/TIFF URLs with pixel dimensions

• Use smithsonian_search_objects with filters.cc0_only: true to find objects with downloadable CC0 images before calling this tool

smithsonian_browse_category tool

• Five modes: museum (by unit code, e.g. "NASM" — matched exactly, not by museum name), culture (e.g. "Aztecs"), period (indexed date term, e.g. "1940s" or "500-1500"), medium (object type, e.g. "Paintings"), topic (subject term, e.g. "Quilts")

• value must be an exact indexed category term — resolve museum, culture, period, and topic vocabulary with smithsonian_list_terms first; object_type is not enumerable there, so harvest it from smithsonian_search_objects results

• Returns total count, a page of sample objects, and a museum breakdown showing which institutions hold matching items (computed from the current page)

• Use start + rows for standard pagination (offset-based, default 10, up to 1,000 per page — a larger rows is served at 1,000 with a notice). When objects remain, the notice names the next start — adjacent pages retrieve the objects a capped sample omits

• A category value that matches nothing throws invalid_category with a mode-specific recovery hint: a value outside the vocabulary gets the exact smithsonian_list_terms call that resolves it, and a value the index enumerates but that matches no objects is named as such and routed elsewhere

• For open-ended or topic discovery, use smithsonian_search_objects instead — this tool requires an exact category value

smithsonian_find_related tool

• Matches shared culture, named-party, topic, and period+type metadata signals against the wider catalog; cross-museum discovery is the differentiator — an NASM aerospace anchor may surface related objects from NMNH, SAAM, and NMAH

• The named-party signal carries the catalog's own role for the party (maker, collector, donor, issuing authority, …) rather than a fixed maker label, prefers the indexed name facet as a hard filter when the record has one, and is dropped when its value only repeats the culture signal

• The topic signal is a hard topic: filter, so every object it tags carries that subject term rather than merely mentioning the word

• similarity_signals on each result names every metadata term that connected it to the anchor — an object surfaced by more than one signal carries all of them

• Page with start — a 0-indexed offset into the interleaved related set (default limit 10, up to 1,000 — a larger limit is served at 1,000 with a notice, and the notice names the next start); each signal is reachable to a depth of 5,000 (fetched in ≤1,000-row chunks — a deeper page can shift an object by a bounded amount near a seam), and a truncated response reports truncationCeiling as an upper bound on the reachable related pool

• signals[] breaks the fan-out down per signal: row_count is that signal's true upstream size (uncapped, so it can exceed the 5,000 reach) and search_continuation is the exact smithsonian_search_objects input that retrieves the signal's full match set at any depth — the retrieval path past this tool's per-signal reach

• Partial failures name the failed signals with safe categories in the same notice as paging guidance. Empty successes distinguish missing anchor signals, no non-anchor matches, and exhausted pages. All-failed searches reject with the first signal failure; caller cancellation always rejects.

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Smithsonian-specific:

• Wraps the Smithsonian Open Access API (14.5M objects across 20+ museums, 5.2M carrying CC0 media) with a free api.data.gov key

• CC0 gating on smithsonian_get_media — only open-access images returned, never restricted content

• Graceful degradation in smithsonian_find_related — a failure in one metadata signal doesn't abort the rest

• Response normalization across heterogeneous museum metadata schemas

• In-process response cache — repeated identical searches, and the get_object → get_media → find_related chain on one record, cost one upstream request per cache lifetime against the shared hourly key budget

• Optional local mirror of the Open Access bulk metadata (below) — object reads and filter-only searches answer from disk instead of spending API requests

Agent-friendly output:

• has_media on every object summary — agents can gate image download calls without an extra lookup (the is_cc0 flag is the metadata license, which the Open Access corpus carries almost everywhere)

• Typed error reasons (no_results, invalid_filter, not_found, no_media, no_images, not_cc0, invalid_id) with recovery hints for each case

• similarity_signals on related-object results let agents explain why objects were surfaced

• total_count on all search responses enables agents to communicate result scope before paginating

• Over-cap page sizes are served at the cap with a notice instead of rejected, and paging notices name the next start outright

• sources and mirror_snapshot on the five object-reading tools, set only when a mirror is configured, say where an answer came from

Getting started

Public Hosted Instance

A public instance is available at https://smithsonian.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "smithsonian-mcp-server": {
      "type": "streamable-http",
      "url": "https://smithsonian.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Requires a free api.data.gov API key — register at https://api.data.gov/signup and set SMITHSONIAN_API_KEY in your config.

Add the following to your MCP client configuration file:

{
  "mcpServers": {
    "smithsonian-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/smithsonian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SMITHSONIAN_API_KEY": "your-api-key"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "smithsonian-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/smithsonian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SMITHSONIAN_API_KEY": "your-api-key"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "smithsonian-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "SMITHSONIAN_API_KEY=your-api-key",
        "ghcr.io/cyanheads/smithsonian-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 SMITHSONIAN_API_KEY=your-api-key bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).

• A free api.data.gov API key — register at https://api.data.gov/signup. Approval is instant.

• Optional: about 17 GB of disk for the full Open Access mirror, and better-sqlite3 on Node.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/smithsonian-mcp-server.git

2. Navigate into the directory:

cd smithsonian-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# Edit .env and set SMITHSONIAN_API_KEY

Configuration

See .env.example for the full list of optional overrides.

Optional Open Access mirror

By default every read goes to the live Smithsonian API, whose key allows 1,000 requests per hour. The server can instead keep a local SQLite copy of the Smithsonian Open Access bulk metadata and answer from it, so a heavy deployment spends far fewer requests. The mirror is off unless SMITHSONIAN_MIRROR_PATH names a file; a default install behaves as described above.

What it serves

• Object reads (smithsonian_get_object, smithsonian_get_media, and the anchor of smithsonian_find_related) come from the mirror once it is built, and go live on a miss or a store error.

• Filter-only searches (an empty or * query) come from the mirror when they stay within a 100,000-index-entry scan budget.

• Free-text searches, over-budget searches, and smithsonian_list_terms stay live.

• Mirror pages run in mirror order, not the live API's, and their notice says so.

Provenance. Every tool except smithsonian_list_terms gains two optional fields when a mirror is configured: sources (oa_mirror, edan_api, or both) and, when part of the answer came from the mirror, mirror_snapshot (the ISO date of the bulk publish).

Build and refresh

bun run build
SMITHSONIAN_MIRROR_PATH=./smithsonian-oa.sqlite bun run mirror:init     # one-time build; resumable
SMITHSONIAN_MIRROR_PATH=./smithsonian-oa.sqlite bun run mirror:refresh  # bring it up to date with the bucket
SMITHSONIAN_MIRROR_PATH=./smithsonian-oa.sqlite bun run mirror:status   # print the sync state

The mirror:* scripts run dist/mirror/cli.js. On the HTTP transport the server refreshes the mirror on SMITHSONIAN_MIRROR_REFRESH_CRON by running mirror:refresh in a child process, so a refresh never stalls requests; on stdio, run mirror:refresh yourself. Only mirror:init starts a build: a refresh of a store that holds nothing fails and asks for mirror:init, and a server whose store has no completed build logs a warning and answers every read live. The store holds the whole corpus, so it needs substantial disk. Never VACUUM it: the facet index stores row ids that VACUUM may renumber.

On Node, the mirror needs the optional peer dependency better-sqlite3; Bun uses its built-in SQLite.

Docker. The image creates /var/lib/smithsonian-mcp-server, owned by the runtime user. Mount a volume there, point SMITHSONIAN_MIRROR_PATH at a file inside it, and build once:

docker exec <container> bun run mirror:init

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t smithsonian-mcp-server .
docker run --rm -e SMITHSONIAN_API_KEY=your-api-key -p 3010:3010 smithsonian-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/smithsonian-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md / AGENTS.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage

• Register new tools in the tools array in src/index.ts

• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.