molanojustin/smithsonian-mcp

A Model Context Protocol (MCP) server for the Smithsonian Institution's Open Access collections. It lets AI assistants such as Claude Desktop search more than 14 million object records and 2.8 million archive records from Smithsonian museums, libraries, archives and research centers, find out what is on display now, and fetch full object records with images and links to the museum websites.
Ask, for example:
> Which Muppets are on display right now at the National Museum of American History?
The assistant calls search_objects(query="muppet", museum="American History", on_view=true) and finds the objects currently on view, such as:
| Objects | Exhibition |
|---|---|
| Elmo, Fozzie Bear, Oscar the Grouch and Rosita puppets | Entertainment Nation |
| Oscar the Grouch's trash can and Mr. Hooper's costume from Sesame Street | Entertainment Nation |
| The Muppets lunch box (1979) | Taking America To Lunch |
Version 2.0 replaces the 28 tools of version 1.x with 5. See Migrating from 1.x and the changelog.
Contents
- Quick Start
- HTTP transport
- Tools
- Resources
- Prompts
- Search tips
- Migrating from 1.x
- Integration
- Requirements
- Testing
- Service Management
- Troubleshooting
Quick Start
You need:
- A free API key from api.data.gov/signup
- uv. uv downloads a compatible Python (3.10 or newer) if one is not already installed.
The server speaks MCP over stdio by default. MCP clients such as Claude Desktop start it on demand; you do not run it in the background yourself. For clients that connect over HTTP, it can also run as a long-lived server; see HTTP transport.
Claude Desktop with uvx (recommended)
Add this to claude_desktop_config.json. It installs and runs the server straight from the GitHub repository, with no clone or virtual environment to manage:
Restart Claude Desktop, then ask "What Smithsonian museums are available?"
Notes:
- The package is not published on PyPI, so --from points uvx at the GitHub repository. Append @ to the URL to pin a version.
- uvx caches the build. To pick up newer commits, run uvx --refresh --from git+https://github.com/molanojustin/smithsonian-mcp smithsonian-mcp once in a terminal.
- If Claude Desktop reports that uvx cannot be found, use its absolute path as the command (which uvx on macOS/Linux, where uvx on Windows).
Other ways to run the server
All of these start the same smithsonian-mcp command and take the API key from the same env block.
npm/npx
The npm package is a small Node.js wrapper that uses uv to install the Python dependencies on first start. It requires Node.js 16 or newer and uv:
You can also install it globally with npm install -g @molanojustin/smithsonian-mcp and run smithsonian-mcp. Run smithsonian-mcp --test to check your API key and connection.
The wrapper keeps the Python environment in a per-user cache directory, one per package version: ~/Library/Caches/smithsonian-mcp on macOS, ~/.cache/smithsonian-mcp (or $XDG_CACHE_HOME) on Linux, and %LOCALAPPDATA%\smithsonian-mcp on Windows. Set UV_PROJECT_ENVIRONMENT to use a different location. Older versions' environments there can be deleted safely.
From a local clone
uv sync creates .venv from uv.lock and installs the smithsonian-mcp command into it. Point Claude Desktop at the clone:
Alternatively, use the installed command directly as "command": "/absolute/path/to/smithsonian-mcp/.venv/bin/smithsonian-mcp" (on Windows, .venv\Scripts\smithsonian-mcp.exe) with "args": ["--transport", "stdio"].
A server run from the clone also reads the clone's .env. --transport stdio keeps it in stdio mode even if that file sets MCP_TRANSPORT=http for HTTP mode.
Python virtual environment without uv
Requires Python 3.10 or newer:
Then use /absolute/path/to/smithsonian-mcp/.venv/bin/smithsonian-mcp as the command, with "args": ["--transport", "stdio"] as above. This installs the newest compatible dependencies rather than the versions pinned in uv.lock.
Docker
Build the image from a clone. The -i flag keeps stdin open for the stdio transport, and -e SMITHSONIAN_API_KEY passes the key from the env block into the container:
To run the container as an HTTP server instead, set MCP_TRANSPORT=http and publish port 8000 on this machine only:
The HTTP endpoint has no authentication: anyone who can reach the port can call the tools and spends your API key's quota. -p 127.0.0.1:8000:8000 keeps the port on this machine; -p 8000:8000 would publish it on every interface of the host, and on Linux Docker's published ports bypass firewalls such as ufw. The image sets MCP_HOST=0.0.0.0 so that the published port reaches the server, and MCP_ALLOWED_HOSTS=localhost,127.0.0.1,::1, so requests naming any other host are refused. To reach the container by another name, add it with -e MCP_ALLOWED_HOSTS=localhost,127.0.0.1,::1,mcp.example.org and control access in front of it. See HTTP transport.