smithsonian-mcp-server

---

概要

Smithsonian の Open Access カタログには、20 以上の博物館にまたがる 1,450 万点の資料が収録されており、そのうち 520 万点には CC0 画像が付属しています。フリーテキストまたはカテゴリーで検索し、博物館、文化、年代、トピックから閲覧して、コレクションを横断したつながりを見つけられます。

ツール

ツール	説明
smithsonian_search_objects	テキストクエリと任意のフィルターを使って、1,450万件のオブジェクトを横断検索します（博物館、種類、日付用語、文化、場所、トピック、名称、学名、メディアタイプ、オンライン限定、CC0）。総件数を含む、厳選された概要を返します。
smithsonian_list_terms	インデックス化されたフィルターフィールド（unit_code、culture、place、date、online_media_type、topic）で有効な用語の語彙を列挙します。無効な値による検索結果の空振りを避けるため、フィルター適用前に呼び出してください。推測した値を正確な用語に解決するには、containsを渡します。unit_codeの用語には博物館名も付属します。
smithsonian_get_object	IDで指定したオブジェクトの正規化されたカタログメタデータを取得します。タイトル、日付、素材、寸法、展示履歴、クレジット表記、識別子が含まれます。
smithsonian_get_media	オブジェクトのCC0ライセンス画像を、複数の解像度（サムネイル、画面表示用、高解像度のJPEG/TIFF）で返します。CC0画像のみを返し、空のリストは決して返しません。オブジェクトがデジタル化されていない場合、画像以外のメディアしかない場合、または制限付き画像しかない場合など、理由を個別のエラー理由で示します。
smithsonian_browse_category	1つの厳密なカテゴリ（博物館、文化、時代、メディア、トピック）に属するオブジェクトを、総件数、オブジェクトのページ、博物館別内訳とともに閲覧します。インデックス化されたカテゴリ用語との完全一致が必要です。
smithsonian_find_related	共通する文化、人物名、トピック、時代のシグナルを照合し、基準となるオブジェクトに関連するコレクション横断のオブジェクトを見つけます。

---

機能リファレンス

smithsonian_search_objects _tool

• 20以上の博物館から1,450万件のオブジェクトをフリーテキスト検索します
• フィルターは強制的なAND条件として追加されます。通常の単語や引用符で囲んだ語句はそれぞれの検索セマンティクスを維持し、有効なLucene式はブール演算の優先順位を保つようグループ化されます。
• filters.online_media_typeでは、Images、3D Models、Sound recordingsなど、smithsonian_list_termsのメディアカテゴリを完全一致で指定できます。これらはインデックスの内容を表すもので、Imagesであっても画像が添付されていることや、CC0画像であることは保証されません。配信可能かどうかはsmithsonian_get_object.media_summaryで確認してください。メディアカテゴリは検索に使用でき、メディアタイプ別の閲覧モードはありません。
• フィルター：博物館のユニットコード、オブジェクトの種類、インデックス化された日付用語（1920s、500-1500、21st century、-2500）、文化、地理上の場所、主題トピック、人物名（name）、学名（scientific_name）、インデックス化されたメディアカテゴリ（online_media_type）、オンライン限定、CC0限定
• topicとnameはフリーテキストではなく、インデックス化された強制条件です。topic: "Quilts"は1,134件に一致しますが、単語だけの検索では2,677件に一致し、name: "Warhol, Andy"は715件に対して421件に一致します。
• 厳選された概要を返します。タイトル、日付、博物館、オブジェクトの種類、サムネイルURL、CC0フラグ、record_idが含まれます。
• 標準的なページネーションにはstartとrowsを使用します（オフセットベース、1ページあたり最大100件）。

---

smithsonian_list_terms _tool

• フィールド：unit_code、culture、place、date、online_media_type、topic。管理された語彙であり、多くの場合は複数形です（例：PaintingではなくPaintings）。検索または閲覧の前に、ここでフィルター値を確認してください。
• containsは大文字と小文字を区別しない部分文字列で語彙を絞り込み、推測した値（例：greek → Greek, Attic）を1回の呼び出しで解決します。unit_codeでは博物館名（National Air and Space → NASM）も照合され、各unit_code用語には博物館名を示すlabelsマップが付属します。
• startとrowsでページネーションします（デフォルトは50件、最大100件）。topic（13万件）とplace（11万4千件）は件数が多いため、containsとの併用に適しています。
• 上流のデータソースから用語ごとのオブジェクト件数は取得できず、用語自体のみ取得できます。
• 各フィールドの語彙はSMITHSONIAN_TERMS_CACHE_TTL_SECONDS（デフォルトは3600秒、0で無効化）でキャッシュされます。上流のデータソースはページ指定を無視し、呼び出しごとに全件を返すため、キャッシュされていない大量の語彙をページごとに取得すると、毎回ダウンロードし直すことになります。
• object_typeはここでは列挙できません。smithsonian_search_objectsの結果にあるobject_typeフィールドから値を収集してください。

smithsonian_get_object _ツール

• 入力：smithsonian_search_objects の record_id — ID を手作業で作成しないでください
• 公開されているカタログ項目を返します：タイトル、日付（すべてラベル付き）、制作者（役割付き）、素材、寸法、場所との関連、文化に関する用語、トピック／主題に関する用語、展示履歴、登録識別子、クレジット表記、権利に関する記述
• メディアの概要も含まれます — 画像の完全な URL を取得するには smithsonian_get_media を呼び出してください
• 空でない注記はすべて、カタログのラベルと掲載順を維持します。description では、認識された説明文のラベルが選択され、管理上の注記はラベル付きのまま保持されます。
• 自然史のメタデータには、すべての scientific_names、報告された taxonomy の階級、有効な小数形式の収蔵地点 coordinates が含まれ、該当する場合はそれぞれに固有のローカリティも含まれます。名前または有効な地点がない場合、配列は空になります。存在しない階級は省略されます。承認済みの学名、ジオコーディング、精度は推測されません。検索では、scientific_names を filters.scientific_name の値としてそのまま使用してください。このフィールドは smithsonian_list_terms では列挙できません。

---

smithsonian_get_media _ツール

• CC0 ライセンスの画像のみを返し、制限付きコンテンツは返しません
• 返せるものがない場合は、次の 3 種類の失敗理由を区別します：no_media（デジタル化されたものがありません）、no_images（メディアはありますが、すべて画像以外です — スキャンされた書籍、3D モデル、録音など。復旧のヒントには存在する種類が記載されます）、not_cc0（画像はありますが、CC0 のものがありません。Forbidden がスローされます）
• 各画像エントリーには、サムネイル（約 120px）、画面表示サイズ（約 800px）、高解像度の JPEG／TIFF URL とピクセル寸法が含まれます
• このツールを呼び出す前に、filters.cc0_only: true を指定して smithsonian_search_objects を使い、ダウンロード可能な CC0 画像があるオブジェクトを検索してください

---

smithsonian_browse_category _ツール

• 5 つのモード：museum（ユニットコードで指定。例："NASM" — 博物館名ではなくコードと完全一致）、culture（例："Aztecs"）、period（索引に登録された年代用語。例："1940s" または "500-1500"）、medium（オブジェクトの種類。例："Paintings"）、topic（主題用語。例："Quilts"）
• value には、索引に登録されたカテゴリ用語を完全一致で指定する必要があります。まず smithsonian_list_terms で museum、culture、period、topic の用語一覧を確認してください。object_type はそこで列挙できないため、smithsonian_search_objects の結果から取得してください
• 合計件数、オブジェクトのサンプルページ、該当するアイテムを所蔵する機関を示す博物館別内訳を返します（現在のページに基づいて算出）
• 通常のページネーションには start と rows を使用してください（オフセット方式。start = page × rows、1 ページあたり最大 50 件）— 隣接するページを取得すると、上限付きサンプルから省略されたオブジェクトを確認できます
• カテゴリ値に一致するものがない場合は、モードに応じた復旧ヒントを伴って invalid_category をスローします。用語一覧にない値の場合は、それを解決できる smithsonian_list_terms の正確な呼び出し方が示されます。索引に登録されているものの、オブジェクトに一致しない値の場合は、その旨が明示され、別の方法に案内されます
• 幅広い探索やトピックの発見には、代わりに smithsonian_search_objects を使用してください — このツールではカテゴリ値を完全一致で指定する必要があります

---

smithsonian_find_related _tool

• 共有する文化、関係者名、トピック、時代＋種別のメタデータシグナルを幅広いカタログと照合します。博物館を横断した発見が特徴です。NASMの航空宇宙関連の基準オブジェクトから、NMNH、SAAM、NMAHの関連オブジェクトが見つかる場合があります
• 関係者名のシグナルには、固定のmakerラベルではなく、カタログに登録されたその関係者の役割（maker、collector、donor、issuing authorityなど）が含まれます。レコードにインデックス済みのnameファセットがある場合は、それを優先して厳密なフィルターとして使用し、その値が文化シグナルと重複するだけの場合は除外します
• トピックシグナルは厳密なtopic:フィルターです。そのため、該当するすべてのオブジェクトには、その語が単に記載されているだけでなく、対象の主題語が付与されています
• 各結果のsimilarity_signalsには、基準オブジェクトとの関連付けに使われたすべてのメタデータ用語が示されます。複数のシグナルで見つかったオブジェクトには、そのすべてが含まれます
• startを使ってページを指定します。これは、関連オブジェクトを交互に並べたセットに対する0始まりのオフセットで、start = page × limitです。各シグナルは深さ5,000件まで取得でき（1,000行以下のチャンクで取得するため、さらに深いページでは境界付近のオブジェクトの位置が一定範囲でずれる場合があります）、レスポンスが切り詰められた場合は、取得可能な関連オブジェクトの上限としてtruncationCeilingが返されます
• signals[]には、シグナルごとのファンアウトが示されます。row_countは、そのシグナルの上流にある実際の件数（上限がないため、取得可能件数の5,000件を超える場合があります）です。search_continuationは、任意の深さでシグナルに一致するすべてのセットを取得するための、正確なsmithsonian_search_objects入力です。このツールのシグナルごとの取得範囲を超えた場合の取得方法となります
• 部分的な失敗では、ページ指定の案内と同じ通知内に、安全なカテゴリで失敗したシグナルが示されます。成功した結果が空の場合は、基準オブジェクトにシグナルがない、基準オブジェクト以外に一致がない、またはページを使い切った、のいずれかが区別されます。すべての検索が失敗した場合は、最初のシグナルの失敗を返して拒否されます。呼び出し元によるキャンセルの場合も、常に拒否されます

---

機能

@cyanheads/mcp-ts-coreを基盤としており、stdioおよびStreamable HTTPトランスポート、切り替え可能な認証（none / jwt / oauth）、交換可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションのOpenTelemetryトレースを備えた構造化ログに対応しています。

Smithsonian固有の機能：

• Smithsonian Open Access API（20館以上の博物館にわたる1,450万点のオブジェクトのうち、520万点にCC0メディアが含まれます）を、無料のapi.data.govキーで利用できます
• smithsonian_get_mediaではCC0による制限を適用し、オープンアクセス画像のみを返し、制限コンテンツは返しません
• smithsonian_find_relatedでは適切に縮退し、1つのメタデータシグナルでエラーが発生しても、ほかのシグナルの処理は中断しません
• 多様な博物館のメタデータスキーマ間でレスポンスを正規化します

エージェントが利用しやすい出力：

• すべてのオブジェクト概要にhas_mediaが含まれるため、エージェントは追加の検索を行わずに画像のダウンロードを判断できます（is_cc0フラグはメタデータライセンスを示し、Open Accessコーパスのほぼすべてのオブジェクトに付与されています）
• 型付きエラー理由（no_results、invalid_filter、not_found、no_media、no_images、not_cc0、invalid_id）と、それぞれのエラーからの復旧方法を示すヒントを提供します
• 関連オブジェクトの結果に含まれるsimilarity_signalsにより、エージェントはオブジェクトが見つかった理由を説明できます
• すべての検索レスポンスにtotal_countが含まれるため、エージェントはページネーションの前に結果の範囲を伝えられます

---

はじめに

公開ホストインスタンス

公開インスタンスhttps://smithsonian.caseyjhand.com/mcpを利用できます。インストールは不要です。Streamable HTTP経由で任意のMCPクライアントから接続してください。

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

セルフホスト／ローカル

無料のapi.data.gov APIキーが必要です — https://api.data.gov/signupで登録し、設定でSMITHSONIAN_API_KEYを設定してください。

MCPクライアントの設定ファイルに以下を追加してください。

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

または、npxを使用します（Bunは不要です）。

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

または、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"
      ]
    }
  }
}

Streamable HTTPを使用する場合は、トランスポートを設定してサーバーを起動してください。

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

前提条件

• Bun v1.4.0 以上（または Node.js v24 以上）。
• 無料の api.data.gov API キー。https://api.data.gov/signup で登録してください。承認は即時です。

インストール

1. リポジトリをクローンします：

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

2. ディレクトリに移動します：

cd smithsonian-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

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

---

設定

変数	説明	デフォルト
SMITHSONIAN_API_KEY	必須。 api.data.gov/signup で取得できる無料の API キーです。	—
SMITHSONIAN_BASE_URL	Smithsonian Open Access API のベース URL です。	https://api.si.edu/openaccess/api/v1.0
SMITHSONIAN_TERMS_CACHE_TTL_SECONDS	インデックス対象の各フィールドの用語ボキャブラリーをキャッシュする秒数です。0 にするとキャッシュは無効になります。	3600
MCP_TRANSPORT_TYPE	トランスポート方式：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	セッションモード：auto、stateful、または stateless。サーバーはコード内で stateless を宣言しています。上書きする場合にのみ設定してください。	stateless
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）。	info
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンドです。	in-memory
OTEL_ENABLED	OpenTelemetry インストルメンテーションを有効にします。	false

オプションの上書き設定の一覧については、.env.example を参照してください。

---

サーバーの実行

ローカル開発

• ビルドして実行：

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

• チェックとテストを実行：

  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

Dockerfile のデフォルトでは、HTTP トランスポート、ステートレスセッションモードを使用し、ログを /var/log/smithsonian-mcp-server に出力します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

---

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツールを登録し、Smithsonian サービスを初期化します。
src/config	サーバー固有の環境変数（SMITHSONIAN_API_KEY、SMITHSONIAN_BASE_URL、SMITHSONIAN_TERMS_CACHE_TTL_SECONDS）を解析します。
src/mcp-server/tools	ツール定義（*.tool.ts）。
src/services/smithsonian	Smithsonian Open Access API のクライアント、正規化、型定義です。
tests/	ユニットテストと統合テストです。
docs/	設計ドキュメントとディレクトリツリーです。

---

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md / AGENTS.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch を使わないでください。
• リクエスト単位のログには ctx.log、テナント単位のストレージには ctx.state を使用してください。
• 新しいツールは src/index.ts の tools 配列に登録してください。
• 外部 API 呼び出しをラップする場合は、生データを検証してからドメイン型に正規化し、出力スキーマに従って返してください。不足しているフィールドを決して捏造しないでください。

---

コントリビューション

Issue を歓迎します。提出前にチェックとテストを実行してください：

bun run devcheck
bun run test

---

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。