met-museum-mcp-server

---

概要

メトロポリタン美術館が所蔵する、5,000 年にわたる 50 万点以上の作品コレクションです。キーワードとフィルターで検索し、部門別に閲覧して、来歴情報や CC0 オープンアクセス画像を含むオブジェクトの全記録を取得できます。

ツール

ツール	説明
met_list_departments	19 の学芸部門すべてについて、数値 ID と表示名を返します
met_search_collections	コレクションをキーワードで検索します。タイトルまたはタグのみを対象にした検索も可能で、部門、年代の範囲、素材、地域、画像の有無、展示中かどうか、ハイライト指定の各フィルターを利用できます
met_list_objects	キーワードを指定せずに、部門内のすべてのオブジェクト ID、指定日以降に作成または改訂されたすべてのオブジェクト ID、またはその両方を一覧表示します
met_get_object	1 つ以上のオブジェクト ID について、メタデータ、来歴情報、作家情報、CC0 画像 URL、タグ、Wikidata リンクを含む全記録を取得します。オプションで、最大 3 点の CC0 画像を画像コンテンツとして取得できます

機能リファレンス

met_list_departments _ツール

• 入力は不要です。19 の学芸部門すべてについて、数値の departmentId と displayName（例：「エジプト美術」）を返します
• departmentId の値は、met_search_collections と met_list_objects の departmentId フィルターに有効な入力値です
• 型付きエラー：upstream_blocked、upstream_unavailable（すべての再試行を通じて Met から 500/502/503/504 が返された場合）、upstream_rate_limited（Met から 429 が返された場合）、retry_deadline_exceeded（呼び出しの制限時間を超過した場合）

---

met_search_collections _ツール

• キーワード q（必須）は、matchField を "title" または "tags" に指定して絞り込まない限り、すべてのテキストフィールドを対象に検索されます。フィルターだけで検索する場合は "*" を指定するとすべてに一致します。フィルター：departmentId、medium（大文字と小文字を区別します。例："Paintings"）、dateBegin／dateEnd（整数の年。負の値は紀元前を表し、両方を指定する必要があります）、geoLocation（1つ）、hasImages、isOnView、isHighlight（true のみ）
• 1ページあたり最大500件のID（デフォルトは20件）を取得できます。offset／nextOffset でページ分割し、最初の10,000件を対象にします。total は全件数を示します。Metでは departmentId 7（The Cloisters）と17（Medieval Art）が1つの結果セットを共有しているため、1ページに limit より少ないIDしか含まれない場合があり、その場合は notice で通知されます。
• 該当なしの場合は、エラーではなく notice を伴う結果が返されます。各結果には、適用されたクエリが effectiveQuery として返されます。型付きエラー：invalid_date_range、invalid_filter（空の q、medium、または geoLocation）、invalid_department、upstream_blocked、upstream_unavailable、upstream_rate_limited、retry_deadline_exceeded

---

met_list_objects _ツール

• departmentId（met_list_departments から取得）と updatedSince（YYYY-MM-DD。その日以降に作成または改訂されたレコード）を、単独または組み合わせて指定できます。どちらも指定しない場合は、コレクション全体（50万件を超えるID）が対象になります。1ページあたり最大500件のID（デフォルトは20件）を昇順で取得できます。offset／nextOffset でページ分割し、深さの制限はありません。
• リストが空の場合は、エラーではなく notice を伴う結果が返されます。各結果には、適用されたフィルターが effectiveQuery として返されます。型付きエラー：invalid_department、invalid_date（2026-02-30 のような存在しない日付）、upstream_blocked、upstream_unavailable、upstream_rate_limited、retry_deadline_exceeded
• リストは最大1時間キャッシュされるため、過去1時間以内に改訂されたレコードはまだ表示されない場合があります。

---

met_get_object _ツール

• met_search_collections または met_list_objects から取得したIDを、1回の呼び出しで重複なしに20件取得します。最大500件のリストを受け付け、最初の20件を超えるIDは remainingIDs に返されます。インデックスに、Metが提供を終了したIDが含まれる場合があるため、404になるIDは除外してください。
• 部分的な成功が可能です。IDごとのエラーは failed[] に記録され、すべてのIDで失敗した場合にのみ呼び出し全体が失敗します（all_not_found、upstream_blocked、upstream_rate_limited、retry_deadline_exceeded、upstream_unavailable、または all_failed）。structuredContent の予算である60,000バイトを超えるレコードは、再リクエストできるよう、サイズとともに deferred[] に記載されます。
• パブリックドメインではないオブジェクト（isPublicDomain／hasCC0Image）では、primaryImage、primaryImageSmall、additionalImages が空になります。includeImages: true を指定すると、CC0画像がある最初の3レコードの画像（約600 px）が、画像コンテンツとして content[] のみに追加され、各レコードの結果は images[] に記載されます。

特長

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

Met Museum 固有の機能：

• Met の公開コレクション API から、5,000 年にわたる 50 万点以上の美術品を取得できます
• The Metropolitan Museum of Art の CC0 オープンアクセスデータを使用しており、許可やクレジット表記なしで自由に利用できます
• met_get_object では、並列バッチ取得の同時実行数を設定できます
• すべてのオブジェクトにリンクされたデータを含みます。Getty ULAN と AAT の URL、アーティスト、タグ、作品の Wikidata エンティティ URL が含まれます
• Met API のエラーはすべてのツールで型付きエラーとして通知されます（403 のファイアウォールブロックは upstream_blocked、5xx は upstream_unavailable、429 は upstream_rate_limited）。Met の生のエラーページが返されることはありません
• Met によるブロック、停止、またはスロットリングが発生すると、met_get_object はバッチの残りのリクエストを停止するため、不正なバッチでもリクエスト数を数件に抑えられます

エージェントに適した出力：

• すべてのレコードに来歴情報を含みます。isPublicDomain と hasCC0Image のフラグで、表示可能な画像を確認できます
• 部分的な失敗を報告します。met_get_object は objects と failed の配列を返すため、成功した結果と ID ごとのエラーをまとめて受け取れます
• 切り詰めを通知します。met_search_collections と met_list_objects は total、returned、truncated、remaining、nextOffset、解決済みの offset を返します
• バイト予算を開示します。バッチが大きすぎる場合、met_get_object はサイズを添えて deferred[] レコードを一覧表示します

はじめに

公開ホストインスタンス

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

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

セルフホスト／ローカル

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

{
  "mcpServers": {
    "met-museum-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/met-museum-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、npx を使う場合（Bun は不要です）：

{
  "mcpServers": {
    "met-museum-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/met-museum-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、Docker を使う場合：

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

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

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• API キーは不要です。Met Collection API は公開されており、認証も必要ありません。

インストール

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

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

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

cd met-museum-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env as needed (all vars are optional)

設定

すべての設定は、src/config/server-config.ts の Zod スキーマを使って起動時に検証されます。

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http	stdio
MCP_HTTP_PORT	HTTP サーバーのポート	3010
MCP_SESSION_MODE	HTTP セッションモード：auto、stateful、または stateless	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error）	info
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗した各ツール呼び出しの引数と結果をログに記録します。キー名を基準に機密情報を除去し、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）でサイズを制限します。自由形式の値に含まれる秘密情報は除去されません。	false
OTEL_ENABLED	OpenTelemetry インストルメンテーションを有効にします	false
MET_BASE_URL	Met Collection API のルート。ローカルのスタブを使う場合に上書きします	https://collectionapi.metmuseum.org/public/collection
MET_REQUEST_TIMEOUT_MS	リクエストごとの HTTP タイムアウト（ミリ秒）	10000
MET_CALL_DEADLINE_MS	1 回のツール呼び出しに使える時間（ミリ秒）。再試行も含みます。超過すると retry_deadline_exceeded で失敗します	30000
MET_BATCH_CONCURRENCY	met_get_object での最大並列取得数	5

オプションの上書き設定の全一覧については、.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 met-museum-mcp-server .
docker run --rm -p 3010:3010 met-museum-mcp-server

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

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツールを登録し、Met サービスを初期化します。
src/config	Zod を使用した、サーバー固有の環境変数の解析と検証です。
src/mcp-server/tools	ツール定義（*.tool.ts）です。met_list_departments、met_search_collections、met_list_objects、met_get_object が含まれます。
src/services/met	Met Collection API クライアントです。HTTP 通信、呼び出し期限、レスポンスの正規化、オブジェクト ID リストのキャッシュを扱います。
tests/	src/ の構成に対応するユニットテストと統合テストです。

開発ガイド

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

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

コントリビューション

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

bun run devcheck
bun run test

データの帰属表示

The Metropolitan Museum of Art Collection API のデータ（CC0）。

ライセンス

Apache-2.0。詳細は LICENSE をご覧ください。