io.github.cyanheads/smithsonian-mcp-server

Official6 toolsLive

by cyanheads · TypeScript

Search 14.5M Smithsonian Open Access objects, get CC0 images, find cross-collection connections.

@cyanheads/smithsonian-mcp-server (Model Context Protocol)

The io.github.cyanheads/smithsonian-mcp-server MCP server searches 14.5M Smithsonian Open Access objects across 20+ museums and retrieves CC0 images. It also finds cross-collection connections, and can return CC0 media for the 5.2M objects that carry openly-licensed media. Tooling is provided via STDIO or Streamable HTTP, with 6 tools.

🛠️ Key Features

Search 14.5M Smithsonian Open Access objects across 20+ museums
Retrieve CC0 images for 5.2M objects with openly-licensed media
Find cross-collection connections
Exposes 6 tools via MCP (STDIO or Streamable HTTP)

🚀 Use Cases

Query Smithsonian Open Access collections and related objects
Obtain CC0 images for downstream indexing or display
Build model workflows that need museum/open-access metadata

⚡ Developer Benefits

MCP-compatible integration for tools (6 total)
Standard transport options: STDIO or Streamable HTTP
Topics align with AI tools and open-access museum data (as provided)

⚠️ Limitations

CC0 image retrieval applies only to the 5.2M objects that include openly-licensed media (per provided description)

Topics

ai-agentsai-toolsartcyanheadsmcpmcp-servermodel-context-protocolmuseumopen-accesssmithsoniantypescript

Captured live from the server via tools/list.

smithsonian_search_objects

Recommended first step for open-ended or topic discovery: free-text search across 14.5 million Smithsonian objects, with optional exact filters. Filters narrow by museum unit, object type, indexed date term, culture, geographic place, subject topic, named party, and online/CC0 availability. Returns curated summaries (title, date, museum, thumbnail URL, CC0 flag) with the total match count. The record_id in each result is the identifier for smithsonian_get_object, smithsonian_find_related, and smithsonian_get_media. To browse one exact category — a single museum, culture, date term, object type, or topic — use smithsonian_browse_category instead.

Parameters4

query	string	required	Free-text search. Use specific terms for precision ("Tlingit totem pole") or broad terms for browsing ("quilt").
filters	object	optional	Optional structured filters to narrow the search.
rows	integer	optional	Page size (default 20, max 100).
start	integer	optional	Pagination offset — 0-indexed. Use with rows for paging through large result sets.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Free-text search. Use specific terms for precision (\"Tlingit totem pole\") or broad terms for browsing (\"quilt\")."
    },
    "filters": {
      "description": "Optional structured filters to narrow the search.",
      "type": "object",
      "properties": {
        "unit_code": {
          "description": "Museum unit code (e.g. \"NASM\", \"SAAM\", \"NMAH\", \"NMAAHC\", \"NMAI\", \"NPG\", \"CHNDM\", \"SIL\"); the National Museum of Natural History is indexed under discipline sub-units like \"NMNHBIRDS\" and \"NMNHPALEO\", not a bare \"NMNH\". The full set is enumerable via smithsonian_list_terms (field \"unit_code\").",
          "type": "string"
        },
        "object_type": {
          "description": "Object type term from Smithsonian's controlled vocabulary — commonly plural (e.g. \"Paintings\", \"Photographs\", \"Aircraft\"). Singular everyday forms like \"Painting\" usually return nothing. This field is not enumerable via smithsonian_list_terms; harvest valid values from the object_type field in smithsonian_search_objects results. Matched exactly and case-sensitively, and casing variants are indexed as SEPARATE categories — \"button\" and \"Button\" each hold their own records, and neither casing is reliably the larger — so probe a harvested value's other casings rather than assuming one covers the concept.",
          "type": "string"
        },
        "date": {
          "description": "Indexed date term. Decades (\"1920s\", \"1960s\") are the most common form, but the vocabulary also carries year ranges (\"500-1500\"), century terms (\"21st century\"), and BCE forms (\"-2500\", \"BCE 1000s\"). The value must be an exact term — the full set is enumerable via smithsonian_list_terms (field \"date\").",
          "type": "string"
        },
        "culture": {
          "description": "Culture term from the controlled vocabulary — often plural or qualified (e.g. \"Aztecs\", \"Plains Indian\"). The vocabulary is enumerable via smithsonian_list_terms (field \"culture\").",
          "type": "string"
        },
        "place": {
          "description": "Geographic place (e.g. \"United States of America\"). The full set is enumerable via smithsonian_list_terms (field \"place\").",
          "type": "string"
        },
        "topic": {
          "description": "Subject term from the controlled vocabulary (e.g. \"Quilts\", \"Aviation\"). Matches the topics[] values smithsonian_get_object returns, and is a hard constraint — topic \"Quilts\" matches 1,134 objects where the same word as free text matches 2,677. The full set is enumerable via smithsonian_list_terms (field \"topic\").",
          "type": "string"
        },
        "name": {
          "description": "Indexed named party — maker, collector, donor, issuing authority, or any other role the catalog records. Written surname-first (e.g. \"Warhol, Andy\"). This field is not enumerable via smithsonian_list_terms. A smithsonian_find_related name signal carries the indexed form verbatim and is the reliable source; smithsonian_get_object's makers[] is the catalog's free-text form of the same parties and is often written differently (\"Major J. A. L. Möller (Jacob A.L. Möller/Monty Möller), Non-Indian, 1883-1957\" for the indexed \"Möller, Major J. A. L.\"), so treat it as a starting guess.",
          "type": "string"
        },
        "online_only": {
          "description": "When true, restrict to records carrying an indexed online_media_type value. That vocabulary covers digitized surrogates — finding aids, catalog cards, scanned books, full text, electronic resources — alongside images, 3D models, and video, and the surrogate types often have no deliverable media attached, so a match can still report has_media: false. Read has_media on each result to decide whether smithsonian_get_media will return anything.",
          "type": "boolean"
        },
        "cc0_only": {
          "description": "When true, restrict to records that have CC0-licensed media attached (the Lucene term media_usage:CC0). This selects on media presence, not license status — the roughly 9.2M records it excludes are CC0 too, they simply have nothing digitized. Read has_media on each result to decide whether smithsonian_get_media will return anything.",
          "type": "boolean"
        }
      }
    },
    "rows": {
      "default": 20,
      "description": "Page size (default 20, max 100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "start": {
      "default": 0,
      "description": "Pagination offset — 0-indexed. Use with rows for paging through large result sets.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

smithsonian_list_terms

Enumerate the valid term vocabulary for an indexed Smithsonian filter field (unit_code, culture, place, date, online_media_type, topic). Terms are a controlled vocabulary — often plural or qualified (e.g. "Paintings", not "Painting") — so guessed filter values tend to return nothing. Returns a page of the field's distinct term values; large vocabularies (topic has 133k terms, place 114k) page via start and rows. For unit_code, each code is returned with its museum name and contains matches the name as well as the code, so a museum name resolves to its code in one call.

Parameters4

field	string	required	Indexed field to enumerate. Choices: unit_code (museum codes like "NASM"), culture (e.g. "Aztecs"), place (geographic terms), date (decade/era values like "1920s"), online_media_type (media formats like "Images", "3D Models"), topic (subject terms like "Quilts" — 133k terms, so pair it with contains).
start	integer	optional	Pagination offset (0-indexed). Use with rows to page through large vocabularies.
rows	integer	optional	Number of terms to return per page (default 50, max 100).
contains	string	optional	Case-insensitive substring filter on the term vocabulary — resolve a filter value (e.g. "greek") to its exact controlled-vocabulary term(s). For unit_code the substring also matches each code's museum name, so "National Air and Space" resolves to "NASM".

Raw schema

{
  "type": "object",
  "properties": {
    "field": {
      "type": "string",
      "enum": [
        "unit_code",
        "culture",
        "place",
        "date",
        "online_media_type",
        "topic"
      ],
      "description": "Indexed field to enumerate. Choices: unit_code (museum codes like \"NASM\"), culture (e.g. \"Aztecs\"), place (geographic terms), date (decade/era values like \"1920s\"), online_media_type (media formats like \"Images\", \"3D Models\"), topic (subject terms like \"Quilts\" — 133k terms, so pair it with contains)."
    },
    "start": {
      "default": 0,
      "description": "Pagination offset (0-indexed). Use with rows to page through large vocabularies.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "rows": {
      "default": 50,
      "description": "Number of terms to return per page (default 50, max 100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "contains": {
      "description": "Case-insensitive substring filter on the term vocabulary — resolve a filter value (e.g. \"greek\") to its exact controlled-vocabulary term(s). For unit_code the substring also matches each code's museum name, so \"National Air and Space\" resolves to \"NASM\".",
      "type": "string"
    }
  },
  "required": [
    "field"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

smithsonian_get_object

Fetch a normalized catalog metadata projection for a Smithsonian object by its record_id (from smithsonian_search_objects results). Returns the exposed catalog fields — title, dates, description, makers, materials, dimensions, places, cultures, topics, exhibitions, credit line, identifiers, rights, and a media summary. The media summary is a count; full image URLs come from smithsonian_get_media.

Parameters1

string

required

Object record_id from smithsonian_search_objects results (e.g. "nasm_A19670093000").

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Object record_id from smithsonian_search_objects results (e.g. \"nasm_A19670093000\")."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

smithsonian_get_media

Return every CC0 (open-access) image for a Smithsonian object at multiple resolutions. The tool never returns an empty list — it names the reason instead: an object with nothing digitized, an object whose media is entirely non-image (scanned books, 3D models, sound recordings), and an object whose images are entirely non-CC0 each fail with their own reason. Each image entry includes thumbnail (~120px), screen-size (~800px), and high-resolution JPEG/TIFF URLs with pixel dimensions. The cc0_only filter on smithsonian_search_objects surfaces objects that have downloadable CC0 images.

Parameters1

string

required

record_id of the object (e.g. "nasm_A19670093000") from smithsonian_search_objects or smithsonian_get_object.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "record_id of the object (e.g. \"nasm_A19670093000\") from smithsonian_search_objects or smithsonian_get_object."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

smithsonian_browse_category

Browse Smithsonian objects within one exact category — a single museum (mode "museum"), culture, indexed date term (mode "period"), object type (mode "medium"), or subject term (mode "topic"). The value must be an exact indexed category term, not free text: resolve museum, culture, period, and topic vocabulary with smithsonian_list_terms first (object_type is not enumerable there — harvest it from smithsonian_search_objects results, and treat each casing as its own category, since a harvested object_type covers only the casing it was written in). Returns the category total count, a page of matching objects, and a museum breakdown of that page; page the full category with start and rows. For open-ended or topic discovery, start with smithsonian_search_objects instead.

Parameters4

mode	string	required	Browse dimension: "museum" (by unit code), "culture" (by culture term), "period" (by indexed date term like "1940s" or "500-1500"), "medium" (by object type like "Paintings"), "topic" (by subject term like "Quilts").
value	string	required	Category value appropriate to the mode. museum: a unit code like "NASM", "SAAM", or "NMNHBIRDS", matched literally and case-sensitively — not a museum name. culture: term, often plural or qualified ("Aztecs", "Plains Indian"). period: an indexed date term — commonly a decade ("1940s", "1860s"), but year ranges ("500-1500"), century terms ("21st century"), and BCE forms ("-2500", "BCE 1000s") are indexed too. medium: object type, usually plural ("Paintings", "Aircraft"). topic: subject term ("Quilts", "Aviation"). Smithsonian uses a controlled vocabulary — for museum (unit_code), culture, period (date), and topic, call smithsonian_list_terms to find exact terms; medium (object_type) is not enumerable there, so harvest it from smithsonian_search_objects results. Every mode matches its value exactly and case-sensitively, and for medium that split is load-bearing: casing variants are indexed as SEPARATE categories, each reporting its own total_count ("button" and "Button" are different categories, and neither casing is reliably the larger), so browse the variants of a harvested value rather than assuming one covers the concept.
rows	integer	optional	Number of sample objects to return (default 10, max 50).
start	integer	optional	Pagination offset — 0-indexed. Page contiguously with start = page × rows.

Raw schema

{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "museum",
        "culture",
        "period",
        "medium",
        "topic"
      ],
      "description": "Browse dimension: \"museum\" (by unit code), \"culture\" (by culture term), \"period\" (by indexed date term like \"1940s\" or \"500-1500\"), \"medium\" (by object type like \"Paintings\"), \"topic\" (by subject term like \"Quilts\")."
    },
    "value": {
      "type": "string",
      "description": "Category value appropriate to the mode. museum: a unit code like \"NASM\", \"SAAM\", or \"NMNHBIRDS\", matched literally and case-sensitively — not a museum name. culture: term, often plural or qualified (\"Aztecs\", \"Plains Indian\"). period: an indexed date term — commonly a decade (\"1940s\", \"1860s\"), but year ranges (\"500-1500\"), century terms (\"21st century\"), and BCE forms (\"-2500\", \"BCE 1000s\") are indexed too. medium: object type, usually plural (\"Paintings\", \"Aircraft\"). topic: subject term (\"Quilts\", \"Aviation\"). Smithsonian uses a controlled vocabulary — for museum (unit_code), culture, period (date), and topic, call smithsonian_list_terms to find exact terms; medium (object_type) is not enumerable there, so harvest it from smithsonian_search_objects results. Every mode matches its value exactly and case-sensitively, and for medium that split is load-bearing: casing variants are indexed as SEPARATE categories, each reporting its own total_count (\"button\" and \"Button\" are different categories, and neither casing is reliably the larger), so browse the variants of a harvested value rather than assuming one covers the concept."
    },
    "rows": {
      "default": 10,
      "description": "Number of sample objects to return (default 10, max 50).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "start": {
      "default": 0,
      "description": "Pagination offset — 0-indexed. Page contiguously with start = page × rows.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "mode",
    "value"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

smithsonian_find_related

Discover objects across Smithsonian collections related to a given anchor object, matched on shared metadata signals — culture, period, object type, named parties, and topic terms. Each related object is tagged with the signals that connected it to the anchor; a named-party signal carries the catalog's own role for that party (maker, Collector, Donor, issuing authority, …), not a fixed "maker" label. Matches surface across museums — an NASM aerospace anchor can pull related objects from NMNHPALEO, SAAM, and NMAH.

Parameters3

id	string	required	record_id of the anchor object (e.g. "nasm_A19670093000") from smithsonian_search_objects or smithsonian_get_object.
limit	integer	optional	Maximum number of related objects to return (default 10, max 20).
start	integer	optional	Pagination offset — 0-indexed. Page contiguously with start = page × limit; each signal is reachable to a depth of 5000 objects, beyond which truncated stays true but deeper pages aren't retrievable.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "record_id of the anchor object (e.g. \"nasm_A19670093000\") from smithsonian_search_objects or smithsonian_get_object."
    },
    "limit": {
      "default": 10,
      "description": "Maximum number of related objects to return (default 10, max 20).",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "start": {
      "default": 0,
      "description": "Pagination offset — 0-indexed. Page contiguously with start = page × limit; each signal is reachable to a depth of 5000 objects, beyond which truncated stays true but deeper pages aren't retrievable.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md17 KBView on GitHub

@cyanheads/smithsonian-mcp-server

Search 14.5M Smithsonian Open Access objects across 20+ museums via MCP, and retrieve CC0 images for the 5.2M that carry openly-licensed media. STDIO or Streamable HTTP.

6 Tools

MCP SDK TypeScript

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

Overview

Smithsonian Open Access catalog — 14.5 million objects across 20+ museums, with CC0 images for the 5.2 million that carry them. Search by free text or exact category, browse by museum, culture, date, or topic, and discover cross-collection connections from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
`smithsonian_search_objects`	Search across 14.5M objects by text query with optional filters (museum, type, date term, culture, place, topic, name, online-only, CC0). Returns curated summaries with total count.
`smithsonian_list_terms`	Enumerate the valid term vocabulary for an indexed filter field (unit_code, culture, place, date, online_media_type, topic). Call before filtering to avoid empty results from invalid values; pass `contains` to resolve a guessed value to its exact term(s). `unit_code` terms come back with their museum names.
`smithsonian_get_object`	Fetch a normalized catalog metadata projection for an object by ID: title, dates, materials, dimensions, exhibition history, credit line, and identifiers.
`smithsonian_get_media`	Return all CC0-licensed images for an object at multiple resolutions (thumbnail, screen, high-res JPEG/TIFF). Only CC0 images returned, never an empty list — a distinct error reason names why, whether the object has nothing digitized, only non-image media, or only restricted images.
`smithsonian_browse_category`	Browse objects within one exact category (museum, culture, period, medium, topic) with total count, a page of objects, and museum breakdown. Requires an exact indexed category term.
`smithsonian_find_related`	Discover cross-collection objects related to an anchor, matched on shared culture, named-party, topic, and period signals.

Capability reference

`smithsonian_search_objects` _tool

Free-text search over 14.5M objects from 20+ museums
Filters: museum unit code, object type, indexed date term (1920s, 500-1500, 21st century, -2500), culture, geographic place, subject topic, named party (name), 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
Use start + rows for standard pagination (offset-based, max 100 per page)

`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, max 100 per page); 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

`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 — scanned books, 3D models, sound recordings; the recovery hint names the types present), 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, start = page × rows, max 50 per page) — 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, start = page × limit; 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

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

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

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:

json

{
  "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:

json

{
  "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):

json

{
  "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:

json

{
  "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.

Installation

Clone the repository:

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

Navigate into the directory:

cd smithsonian-mcp-server

Install dependencies:

bun install

Configure environment:

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

Configuration

Variable	Description	Default
`SMITHSONIAN_API_KEY`	Required. Free API key from api.data.gov/signup.	—
`SMITHSONIAN_BASE_URL`	Smithsonian Open Access API base URL.	`https://api.si.edu/openaccess/api/v1.0`
`SMITHSONIAN_TERMS_CACHE_TTL_SECONDS`	Seconds to cache each indexed field's term vocabulary. `0` disables caching.	`3600`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	Port for HTTP server.	`3010`
`MCP_SESSION_MODE`	Session mode: `auto`, `stateful`, or `stateless`. The server declares `stateless` in code; set this only to override it.	`stateless`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`LOGS_DIR`	Directory for log files (Node.js only).	`<project-root>/logs`
`STORAGE_PROVIDER_TYPE`	Storage backend.	`in-memory`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation.	`false`

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

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

Directory	Purpose
`src/index.ts`	`createApp()` entry point — registers tools and initializes the Smithsonian service.
`src/config`	Server-specific environment variable parsing (`SMITHSONIAN_API_KEY`, `SMITHSONIAN_BASE_URL`, `SMITHSONIAN_TERMS_CACHE_TTL_SECONDS`).
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`).
`src/services/smithsonian`	Smithsonian Open Access API client, normalization, and type definitions.
`tests/`	Unit and integration tests.
`docs/`	Design document and directory tree.

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 via the barrel in src/mcp-server/tools/definitions/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.

Install

Tools (6)

smithsonian_search_objectssmithsonian_list_termssmithsonian_get_objectsmithsonian_get_mediasmithsonian_browse_categorysmithsonian_find_related

Configuration

Environment variables

SMITHSONIAN_API_KEYrequired

Required. Free API key from https://api.data.gov/signup — approval is instant.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "smithsonian-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/smithsonian-mcp-server@0.3.7",
        "run",
        "start:stdio"
      ],
      "env": {
        "SMITHSONIAN_API_KEY": "<YOUR_SMITHSONIAN_API_KEY>",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

@cyanheads/smithsonian-mcp-server (Model Context Protocol)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

smithsonian_search_objects

smithsonian_list_terms

smithsonian_get_object

smithsonian_get_media

smithsonian_browse_category

smithsonian_find_related

@cyanheads/smithsonian-mcp-server

Overview

Tools

Capability reference

smithsonian_search_objects tool

smithsonian_list_terms tool

smithsonian_get_object tool

smithsonian_get_media tool

smithsonian_browse_category tool

smithsonian_find_related tool

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`smithsonian_search_objects` _tool

`smithsonian_list_terms` _tool

`smithsonian_get_object` _tool

`smithsonian_get_media` _tool

`smithsonian_browse_category` _tool

`smithsonian_find_related` _tool