art-institute-chicago-mcp-server

---

概要

シカゴ美術館のコレクションには、約 133,000 点の美術作品のほか、アーティスト、展覧会、音声ガイドのスポットが含まれています。フィルターとファセット件数を使って検索し、来歴や IIIF 画像 URL を含む完全なレコードを読み込み、音声ガイドの文字起こしを検索できます。API キーは不要です。

ツール

ツール	説明
artic_search_artworks	テキストとフィルターで美術作品を検索します。ファセット件数と日付順の並べ替えに対応しています
artic_get_artworks	最大 10 点の美術作品について、説明、来歴、履歴、権利状況付きの画像 URL、関連メディアを含む完全なレコードを取得します
artic_search_artists	名前または ID でアーティスト、文化、組織を検索します。利用可能な Getty ULAN 識別子、生没年、美術作品数、代表作品を確認できます
artic_search_exhibitions	テキスト、日付、美術作品 ID、アーティスト ID で、過去、開催中、今後の展覧会を検索します
artic_search_audio_guide	テキストで音声ガイドのスポットを検索します。タイトル、MP3 URL、文字起こしを取得できます
artic_lookup_vocabulary	検索フィルターで使用できる値と、それぞれに該当する美術作品数を一覧表示します

リソース

リソース	説明
artic://artworks/{id}	API のライセンス文と説明の帰属表示を含む、美術作品 1 点の JSON レコード

artic_get_artworks は、リソースを表示しないクライアント向けに同じレコードを返します。

機能リファレンス

検索と語彙の検索では最大1,000件まで指定でき、適用された上限がレスポンスに記載されます。作品は12件、アーティスト検索と展覧会は25件、音声ガイドは2件、語彙は100件です。next_page を使って次のページを取得するときも、同じリクエスト上限を指定してください。ページ数と適用された件数の積は1,000以内にする必要があります。語彙が上限に達した場合は、contains で絞り込んでください。

artic_search_artworks _tool

• query（すべての単語が一致する必要があります。"exact phrase"、-exclude、a | b が使用できます）と、フィルター artist、artist_id、department、artwork_type、style、subject、classification、material、technique、theme、place_of_origin、gallery、year_from / year_to（期間の重複で照合。BCE は負の値）、public_domain_only、on_view_only、has_image を指定できます。複数指定した場合は AND で結合されます
• 1ページあたり最大12件（デフォルトは10件）で、最初の1,000件の一致結果が対象です。sort は relevance、date_asc、date_desc のいずれかです。クエリ文字列なしで関連度順が指定された場合、sort_applied には popularity と報告されます
• facets を指定すると、最大7フィールドについて上位15件の値が追加されます（artist はクレジットされたアーティスト全員を集計し、各行には artist_id が含まれます）。limit: 0 を指定すると件数のみが返されます

---

artic_get_artworks _tool

• ids には最大1,000件を指定できます（カンマ区切りの文字列は最大100,000文字）。空欄と重複は除外され、作品ページのURLは ID として読み取られます。最初の10件が取得されます。sections では、description と provenance（デフォルト）、exhibition_history、publication_history、catalogue から選択できます
• レコードはリクエスト順に返されます。missing_ids には美術館が所蔵していない ID が、deferred_ids にはレスポンスの予算の都合で保留されたレコードと未処理の ID が列挙されます。これらは同じツールに再度渡してください
• include_related_media（デフォルトで有効）を指定すると、関連する講演と音声ガイドのスポットが最大20件読み込まれます。CC BY の解説テキストが返される場合は、常に description_attribution が含まれます

---

artic_search_artists _tool

• query（名前のすべての単語が一致する必要があります）または ids を指定します。両方は指定できません。ids には最大1,000件を指定でき（カンマ区切りの文字列は最大100,000文字）、最初の25件が取得されます。クエリモードでは artists_only（デフォルトは true）、born_from / born_to、および1ページあたり最大25名のエージェントを指定できます
• 各エージェントには artwork_count、最大3件の sample_works（美術館の注目作品が先頭）、生没年、alt_names が含まれます。ID モードでは missing_ids と deferred_ids が報告されます。次回の呼び出しでは、これらを ID として渡してください
• ulan_id は、美術館が記録している場合の Getty ULAN 識別子です。該当する記録は限られており、他のツールで使用される美術館の id とは異なります

---

artic_search_exhibitions _tool

• query、when（current、upcoming、past、またはデフォルトの any）、date_from / date_to（YYYY-MM-DD。会期の重複で照合）、および完全一致の artwork_id / artist_id フィルターを指定できます。複数指定した場合は AND で結合されます。最初の1,000件の一致結果から、1ページあたり最大25件が返されます
• 関連性フィルターが対象とするのは、美術館に記録されたリンクです。リンクがないからといって、作品やアーティストが展覧会に出品されたことが一度もないとは限りません
• sort は relevance、start_desc、start_asc のいずれかです。デフォルトでは、クエリがある場合は relevance、ない場合は start_desc で並べ替えられます。status は美術館によるラベルであり、展覧会が開催中かどうかを示すものではありません（開催状況は when で指定します）
• 美術館が記録している場合、各行には日付、ギャラリー、概要、ウェブページ、画像、artist_ids、および展示作品 artworks が含まれます

---

artic_search_audio_guide _tool

• query は必須で、スポットのタイトルと書き起こしが検索対象になります（すべての単語が一致する必要があります）。1ページあたり最大2件のスポット全体が返されます（デフォルトは2件）
• 各スポットには title、audio_url（MP3）、transcript が含まれますが、作品 ID は含まれません。すべてのレスポンスに license_text と source_citation が含まれます（コンテンツは非営利の教育目的および個人利用が対象です）

artic_lookup_vocabulary _ツール

• vocabulary は department、artwork_type、style、subject、classification、material、technique、theme、place_of_origin、gallery のいずれかです。任意で contains 部分文字列（大文字・小文字とアクセント記号を区別しないため、applique で appliqué (technique) が見つかります）、public_domain_only、最大100件の値を指定できます（デフォルトは25件）
• 値は artwork_count とともに頻度の高い順で返され、同名の artic_search_artworks フィルターが受け付けるものと完全に同じ形式です。filter_param はそのフィルター名を示します

---

artic://artworks/{id} _リソース

• application/json として { artwork, license_text, description_attribution?, notice? } を返します。artwork は、デフォルトのセクションと関連メディアを含む artic_get_artworks のレコードです
• 不明な ID を指定すると artwork_not_found エラーになります。ID は artic_search_artworks から取得できます

機能

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

Art Institute 固有の機能：

• Art Institute of Chicago の公開 API（api.artic.edu/api/v1）をキーなしで利用できます。IIIF 画像 URL は各レコードから構築され（すべての画像で843 px、パブリックドメインの作品では1686 px と IIIF マニフェスト）、画像の取得は行いません
• API が公表している毎分60リクエストの上限を下回るよう、共有リクエストペーサーを使用します。20秒の期限内で一時的な障害を再試行し、レスポンスをプロセス内にキャッシュします（レコードは6時間、検索結果は15分、語彙は24時間）
• テキスト検索では、すべての単語が一致する必要があるため、合計件数は実数で、該当なしの場合はヒット数が0になります。結果は美術館の関連度順を維持します
• 美術館のデータにある仮の年（−8000から2100の範囲外）は、出力、年フィルター、日付順の並べ替えから除外されます。日付については date_display が常に正となります

エージェント向けの出力：

• 権利情報をデータとともに返します。すべての画像に image.rights（public_domain / in_copyright）を含め、再利用が許可されている場合にのみ1686 pxの URL を返します。また、API の license_text をそのまま返し、CC BY のテキストが返される場合は description_attribution を、音声ガイドの結果には source_citation を含めます
• 失敗ではなく部分的な結果を返します。artic_get_artworks は missing_ids と deferred_ids を報告します。また、関連メディアやアーティスト件数などの二次検索に失敗した場合も、何が欠落しているかを示す notice とともにプライマリレコードを返します
• 次に行う操作がわかるページネーションに対応します。totalCount、has_more、next_page に加え、次のページ、1,000件の上限、またはヒット数が0件の場合に緩和すべきフィルターを知らせる notice を返します

データとライセンス

Art Institute of Chicago は、提供する情報の種類ごとに API データのライセンスを定めており、サーバーはすべての作品、アーティスト、展覧会、音声ガイドの結果とともに、API 独自の license_text をそのまま渡します。

コンテンツ	利用条件
作品のメタデータ、アーティスト、展覧会、語彙の用語、関連メディア	CC0
作品の description テキスト	CC BY 4.0：Art Institute of Chicago をクレジットし、レコードの web_url を引用してください
作品画像	パブリックドメインの作品のみ再利用できます（image.rights: "public_domain"、CC0）。それ以外の画像については権利の確認が必要です
音声ガイドのコンテンツ	非商用の教育目的および個人利用に限ります。著作権表示を残し、出典を引用してください

このサーバーは独立したプロジェクトであり、Art Institute of Chicago とは提携しておらず、同館からの推奨も受けていません。

既知の制限事項

• 認証済みキーがない場合、検索結果は先頭の1,000件までしか取得できません。範囲の広い質問には、フィルターやファセットが必要です。
• API のリクエスト上限は送信元 IP あたり毎分 60 件のため、同じ IP を使うすべてのクライアントで共有されます。20 秒の制限時間内に開始できない呼び出しは、rate_limited として失敗します。
• 学芸員による解説は限られています。作品の約 10％にしか description がなく、一般的なサンプルでは 94％に来歴情報がありません。アーティストの約 1％にしか略歴がなく、国籍フィールドもありません。あるのは artist_display の文章のみです。
• 約 15 点の作品にはプレースホルダーの年が設定されており、約 4,900 点には日付がありません。どちらも年フィルターには一致しません。
• 一部の用語のタイトルは、美術館のデータ内で 40 文字で切り詰められています（gelatin silver (developing-out-paper) pr）。artic_lookup_vocabulary が一覧表示する値を渡してください。
• API のファイアウォールは、<script> などのマークアップを含むテキストのリクエストを拒否します。この呼び出しは request_blocked として失敗します。
• 展覧会の約 4％に作品が掲載されています。
• オーディオガイドの各スポットには作品へのリンクがありません。タイトルがファイル名になっているものや、スペイン語の文字起こしもあります。
• 美術館が画像を非公開にしたり、差し替えたりすると、画像 URL が解決できなくなることがあります。また、関連度順は美術館のランキングに従うため、変わる場合があります。

はじめに

公開ホストインスタンス

公開インスタンスは https://art-institute-chicago.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP で提供されており、クライアントごとに設定形式が異なります。

Claude Code の場合：

claude mcp add --transport http art-institute-chicago-mcp-server https://art-institute-chicago.caseyjhand.com/mcp

Cline の場合（cline_mcp_settings.json）：

{
  "mcpServers": {
    "art-institute-chicago-mcp-server": {
      "type": "streamableHttp",
      "url": "https://art-institute-chicago.caseyjhand.com/mcp"
    }
  }
}

Cursor の場合（mcp.json）：

{
  "mcpServers": {
    "art-institute-chicago-mcp-server": {
      "url": "https://art-institute-chicago.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop では、Settings → Connectors からリモートサーバーを追加します。

ホストインスタンスを呼び出すすべてのクライアントで、api.artic.edu へのリクエスト上限を毎分 50 件まで共有します。継続的に利用する場合は、ご自身のインスタンスを実行してください。

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加してください。API キーは不要です。AIC_CONTACT は美術館から連絡を取る方法を指定します（設定を参照）。

{
  "mcpServers": {
    "art-institute-chicago-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/art-institute-chicago-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "AIC_CONTACT": "[email protected]"
      }
    }
  }
}

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

{
  "mcpServers": {
    "art-institute-chicago-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/art-institute-chicago-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "AIC_CONTACT": "[email protected]"
      }
    }
  }
}

または Docker を使用する場合：

{
  "mcpServers": {
    "art-institute-chicago-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "[email protected]", "ghcr.io/cyanheads/art-institute-chicago-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 キーやアカウントは不要です。Art Institute API は、クライアントに連絡先の提示を求めています。AIC_CONTACT にメールアドレスまたは URL を設定してください。

インストール

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

git clone https://github.com/cyanheads/art-institute-chicago-mcp-server.git

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

cd art-institute-chicago-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set AIC_CONTACT

設定

変数	説明	デフォルト
AIC_CONTACT	美術館から連絡を取るためのメールアドレスまたは URL。AIC-User-Agent ヘッダーで送信されます。印字可能な ASCII 文字のみ使用できます。これ以外の場合、サーバーは起動を拒否します。デプロイごとに独自の値を設定してください。	https://github.com/cyanheads/art-institute-chicago-mcp-server
AIC_REQUESTS_PER_MINUTE	api.artic.edu への 1 分あたりの送信リクエスト数。1～600 に設定できます。API が公表している上限の 60 件以内に収めてください。美術館からより高い上限が認められた場合にのみ引き上げてください。	50
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。サーバーが宣言する動作設定を上書きします。	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。	info
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	OpenTelemetry を有効にします。	false

すべてのサーバー設定と共通フレームワークのオーバーライドについては、.env.example を参照してください。

サーバーの実行

ローカル開発

• 本番環境向けバージョンをビルドして実行する：

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

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

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツールとリソースを登録し、サーバーの指示を設定して、API サービスを起動および停止します。
src/config	Zod を使用して AIC_CONTACT と AIC_REQUESTS_PER_MINUTE を解析および検証します。
src/mcp-server/tools	ツール定義（*.tool.ts）と、ツール間で共有する作品の出力スキーマです。
src/mcp-server/resources	artic://artworks/{id} リソースです。
src/services/aic	Art Institute API クライアントです。アクセス間隔の調整、再試行、レスポンスキャッシュ、HTML からテキストへの変換、IIIF URL の構築、作品およびアーティストのレコード作成を行います。
tests/	src/ の構成に対応する単体テストと統合テストです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークがキャッチします。ツールのロジックで try/catch を使用しないでください。
• ログには ctx.log を、ページングや通知には ctx.enrich を使用してください。
• 新しいツールとリソースは、src/mcp-server/*/definitions/index.ts のバレルファイルに登録してください。
• 外部 API 呼び出しはラップしてください。生データを検証し、ドメイン型に正規化してから、出力スキーマに沿って返します。不足しているフィールドを捏造しないでください。

コントリビューション

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

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 License のもとでライセンスされています。詳細については、LICENSE ファイルを参照してください。