unesco-heritage-mcp-server

---

概要

UNESCO の世界遺産一覧、無形文化遺産一覧、生物圏保存地域、世界ジオパークを検索できます。全記録を検索・閲覧し、危機にさらされている世界遺産一覧を確認できます。また、任意の地点の近くにある遺産、保存地域、ジオパークを探せます。API キーは不要です。

ツール

ツール	説明
unesco_search_sites	キーワード、国、カテゴリ、地域、基準、登録年、危機遺産リストへの登録状況または国境を越える遺産の状況、あるいは地点からの距離で世界遺産を検索します
unesco_get_site	遺産の完全な記録を取得します。顕著な普遍的価値の言明、基準とその意味、構成資産、座標、画像クレジットが含まれます
unesco_search_intangible_heritage	キーワード、国、リスト、登録年、多国間登録の状況、または関連する世界遺産で、無形文化遺産の3つのリストを検索します
unesco_get_intangible_heritage_element	要素の完全な記録を取得します。説明、リスト、国、概念用語、関連する遺産、画像クレジットが含まれます
unesco_search_biosphere_reserves	キーワード、国、地域、MAB地域ネットワーク、登録年、国境を越える状況またはSIDSの状況、あるいは地点からの距離で生物圏保存地域を検索します
unesco_get_biosphere_reserve	保存地域の完全な記録を取得します。生態学的および社会経済的な概要、ゾーニングされた区域と人口、見直し年、座標が含まれます
unesco_search_geoparks	キーワード、国、登録年、国境を越える状況、あるいは地点からの距離でユネスコ世界ジオパークを検索します
unesco_get_geopark	ジオパークの完全な記録を取得します。紹介、説明、地域コミュニティを支える仕組みの説明、記録された面積と人口、座標が含まれます
unesco_list_reference	基準、国（名称からISOコードへの変換）、地域、無形文化遺産リスト、MABネットワークを照合し、データセットの対象範囲とデータの日付を報告します

リソース

リソース	説明
unesco://site/{id_no}	1件の世界遺産の記録
unesco://intangible-heritage/{ich_ref}	1件の無形文化遺産要素の記録
unesco://biosphere-reserve/{mab_id}	1件の生物圏保存地域の記録
unesco://geopark/{ugg_id}	1件のユネスコ世界ジオパークの記録

各リソースは、対応する取得ツールと同じ内容を提供します。

機能リファレンス

unesco_search_sites _ツール

• フィルター：query、country（ISO 3166-1 alpha-2またはalpha-3）、category、region、criteria（指定したすべての基準が必須）、in_danger、transboundary、inscribed_from／inscribed_to、およびnear（latitude、longitude、最大5000のradius_km。デフォルトは100）。遺産の代表地点または構成資産のいずれかを通じて一致します
• 1ページあたり最大50件の遺産を返します（デフォルトは20件。最大10,000件のより大きなlimitを指定した場合は50件ずつ返し、その旨をnoticeで示します）。next_cursorで続きを取得します。sortにはrelevance、name、inscribed_newest、inscribed_oldest、area_largest、danger_listed_newest、distanceを指定できます。include_description: falseを指定すると、行の説明が省略されます
• in_danger: trueは「危機にさらされている世界遺産リスト」を表します。totalCountとfacets（カテゴリ、地域、危機遺産の状況、基準、上位10か国）は一致する結果全体を対象とします。queryが設定されている場合、行にはmatched_inが含まれます。nearが設定されている場合は、遺産の地点のうち最も近い地点までのdistance_kmが含まれます（構成資産のほうが近い場合はnearest_componentも含まれます）

---

unesco_get_site _ツール

• id_no による1件の遺産：数値、数字の文字列、または遺産の whc.unesco.org ページ URL を指定します。max_components では最大1000件の構成資産を一覧表示します（デフォルトは20です。より大きな値を指定した場合、最大10,000までは1000件として返され、その旨が notice に記載されます）
• 説明、顕著な普遍的価値に関する声明、意味と source: "recorded" | "inferred" を含む criteria[]、締約国と ISO コード、座標、面積、secondary_years、危機遺産リストへの登録年、6言語での名称、クレジット付きのメイン image
• description_language（en、fr、es、ru、ar、zh）を指定すると、その言語での UNESCO の説明を返し、description_language に言語を記載します。UNESCO がその言語の説明を公開していない場合は、英語の説明が en として返され、その旨が notice に記載されます。顕著な普遍的価値に関する声明は英語のみです
• components_total は UNESCO による構成資産数、components_unparsed は読み取れなかった項目です。不明な ID の場合は site_not_found エラーになります

---

unesco_search_intangible_heritage _ツール

• フィルター：query、country、list（代表リスト、緊急保護リスト、優れた保護事例の登録簿。RL ／ USL ／ Art18 も指定できます）、multinational、world_heritage_site（id_no）、inscribed_from ／ inscribed_to
• 1ページあたり最大50件（デフォルトは20件です。より大きな limit を指定した場合、最大10,000までは50件として返され、その旨が notice に記載されます）。next_cursor で続きのページを取得できます。各行には説明は含まれず、主要な concepts と関連する world_heritage_sites が含まれます
• facets には、リスト、多国間該当状況、上位10か国、上位10件の概念用語が含まれます

---

unesco_get_intangible_heritage_element _ツール

• ich_ref による1件の要素：数値、数字の文字列、または要素の ich.unesco.org ページ URL を指定します
• 説明、リスト、国、登録年、主要および副次的な concepts、関連する world_heritage_sites、UNESCO のページ、キャプションとクレジット付きのメイン image。不明な参照番号の場合は element_not_found エラーになります
• description_language: "fr" を指定すると、UNESCO のフランス語の説明を返します（UNESCO が公開している言語は英語とフランス語のみです）。英語へのフォールバックと notice は unesco_get_site と同じです

---

unesco_search_biosphere_reserves _ツール

• フィルター：query（名称、概要、生態学的または社会経済的なテキスト。バイオームのフィールドはないため、生息環境に関する語句で検索してください）、country、region、regional_network（名称または略称）、transboundary、sids、designated_from ／ designated_to、near
• 1ページあたり最大50件（デフォルトは20件です。より大きな limit を指定した場合、最大10,000までは50件として返され、その旨が notice に記載されます）。next_cursor で続きのページを取得できます。sort には relevance、name、designated_newest、designated_oldest、area_largest、distance を指定します。include_description: false を指定すると、各行の概要が省略されます
• 国境を越える保護区は参加国ごとに1回ずつ表示され、それぞれに独自の mab_id が付与されます。facets には地域、地域ネットワーク、国境を越える保護区と SIDS の該当状況、上位10か国が含まれます

---

unesco_get_biosphere_reserve _ツール

• mab_id による1件の保護区。大文字・小文字およびアクセントの違いは区別されません
• 概要、生態学的および社会経済的特性、ゾーン別の陸域・海域面積、ゾーン別人口、登録、拡張、名称変更、定期レビューの各年、座標、ウェブサイト、UNESCO のページ
• 面積（ヘクタール）と人口は記録どおりに返されます。ゾーンの合計が総計と異なる場合や、人口 0 が無人または未報告を意味する場合があります。不明な ID の場合は biosphere_reserve_not_found エラーになります

---

unesco_search_geoparks _tool

• フィルター：query（名称、紹介文、説明、コミュニティアカウント。火山やカルストなどの地形に関する語句で検索）、country、transnational、designated_from / designated_to、および各ジオパークの一点までの距離で測定するnear
• 1ページあたり最大50件のジオパークを返します（デフォルトは20件。limitを大きくして最大10,000件を指定した場合も、50件として処理され、その旨がnoticeに記載されます）。next_cursorで続きのページを取得します。sortにはrelevance、name、designated_newest、designated_oldest、area_largest、distanceを指定できます。include_description: falseを指定すると、各行から紹介文が省かれます
• 越境ジオパークは、該当する各国を列挙した1行として表示されます。facetsには越境の有無と上位10か国が含まれます。範囲の開始年が2015年以前の年指定がある場合、指定制度が始まる前に認定されたジオパークの年は2015年として記録されている旨のnoticeが追加されます

---

unesco_get_geopark _tool

• ugg_id（例：EUFR10）でジオパークを1件取得します。大文字と小文字は区別されません
• 記録されている国、認定年、越境の有無、面積、人口（UNESCOに記録がない場合、populationは含まれません）、座標、紹介文、説明、地域コミュニティの維持に関する記述、ウェブサイト、UNESCOのページを返します。不明なIDの場合はgeopark_not_foundエラーになります

---

unesco_list_reference _tool

• topic：criteria、countries、regions、intangible_lists、biosphere_networks、またはdatasets
• filterを指定すると一致する行に絞り込まれます。countriesでは、国名、ISOコード、または一般的に使われる旧国名を指定すると、country入力で受け付けられるコードと、その国の遺産、無形文化遺産、保護区、ジオパークの件数が返されます
• datasetsでは、各データセットのレコード件数、data_as_of、ライセンス、クレジット表記、対象範囲に関する注記が返されます

---

unesco://site/{id_no} _resource

• unesco_get_siteのレコードを最大20件の構成要素とともに返します（全件数はcomponents_totalに記載）。英語の説明とsourcesも含まれ、形式はapplication/jsonです。id_noはunesco_search_sitesから取得します

---

unesco://intangible-heritage/{ich_ref} _resource

• unesco_get_intangible_heritage_elementのレコードを返します。英語の説明とsourcesも含まれ、形式はapplication/jsonです。ich_refはunesco_search_intangible_heritageから取得します

---

unesco://biosphere-reserve/{mab_id} _resource

• unesco_get_biosphere_reserveのレコードとsourcesを返します。形式はapplication/jsonです。mab_idはunesco_search_biosphere_reservesから取得します。非ASCII文字が含まれる場合はパーセントエンコードします

---

unesco://geopark/{ugg_id} _resource

• unesco_get_geoparkのレコードとsourcesを返します。形式はapplication/jsonです。ugg_idはunesco_search_geoparksから取得します

特長

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

UNESCO 固有の機能：

• データセット whc001（世界遺産リスト）、ich001（無形文化遺産リスト）、mab001（人間と生物圏計画）、eg0001（ユネスコ世界ジオパーク）は、それぞれ初回利用時にインメモリスナップショットとして読み込まれ（上流へのリクエストは 2 回）、24 時間ごとに更新されます。検索、ファセット、距離計算はローカルで実行され、更新に失敗した場合は前回のスナップショットを引き続き提供します
• 上流へのトラフィックは、同時リクエスト数を 2 件、1 日あたりのリクエスト数を最大 200 件に制限し、429 の後は Retry-After に従ってクールダウンします
• UNESCO の基準フィールドでは省略されている基準（vi）は、各サイトの顕著な普遍的価値に関する声明から推定され、該当する箇所では推定値として示されます
• 国の入力には大文字・小文字を問わず ISO 3166-1 alpha-2 または alpha-3 コードを使用でき、その国が参加するすべての越境サイト、多国籍の遺産、越境ジオパークに一致します。サイト ID と遺産 ID には UNESCO のページ URL も使用できます

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

• すべてのレスポンスに出典情報を付与します。sources には各データセットの data_as_of 日付、ライセンス、クレジット表記が含まれます
• 検索結果には一致した全件の情報が含まれます。totalCount、facets、およびサーバーが実行したフィルターと並べ替えを反映する applied_filters が含まれます
• キーワード照合では、すべての単語が必要な単語プレフィックス検索を行います（異なる単語は最大 16 個）。matched_in には一致したフィールドの階層が示されます。一致件数がゼロの場合、notice には、どのフィルターを削除すれば最も多くのレコードに一致するかが示されます
• 型付きエラー（unknown_country、invalid_year_range、sort_needs_input、cursor_mismatch、invalid_cursor、*_not_found、snapshot_unavailable）には、次に呼び出すべき内容を示す復旧ヒントが含まれます。Data Hub に到達できない場合、snapshot_unavailable は retryAfter を含む再試行可能なエラーになります。リクエストが拒否された場合、またはサーバーが利用できないデータを受け取った場合は、再試行できません

データとライセンス

4 つのデータセットはすべてUNESCO Data Hubから取得され、CC BY-SA 4.0 のライセンスで提供されています。データを再利用する場合は UNESCO のクレジットを表示してください。各レスポンスの sources ブロックには、そのまま使えるクレジット表記が含まれます。継承（ShareAlike）条項により、改変したデータは同じライセンスで共有する必要があります。

画像はこのライセンスの対象外です。世界遺産と無形文化遺産の各画像にはそれぞれ独自の著作権があり、権利者と撮影者の情報は画像レコードに含まれています。サーバーは画像へのリンクを返しますが、画像の取得やプロキシは行いません。

このサーバーは独立したプロジェクトであり、UNESCO とは提携しておらず、UNESCO の推奨を受けているものでもありません。

はじめに

公開ホストインスタンス

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

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

セルフホスト／ローカル

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

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

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

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

または Docker を使用します。

{
  "mcpServers": {
    "unesco-heritage-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/unesco-heritage-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 キーやアカウントは不要です。UNESCO Data Hub は公開されています。

インストール

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

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

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

cd unesco-heritage-mcp-server

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

bun install

4. 環境を設定します（任意）：

cp .env.example .env
# edit .env to change the transport, port, or log level

設定

このサーバー固有の設定はありません。以下のフレームワーク変数が適用されます。

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_HTTP_HOST	HTTP サーバーのホスト。	127.0.0.1
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。.env.example と Docker イメージでは stateless が設定されています。	auto
MCP_AUTH_MODE	認証方式：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。	info
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<app-root>/logs
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() のエントリーポイントです。ツールとリソースを登録し、src/mcp-server/instructions.ts のサーバー指示を提供して、サービスを起動・停止します。
src/mcp-server/tools	ツール定義（*.tool.ts）。
src/mcp-server/resources	データセットごとに1つのレコードリソース。
src/mcp-server/shared	ツールとリソースで共有する入力スキーマと正規化処理、拡張フィールド、Markdown ヘルパー。
src/services/unesco-datahub	UNESCO Data Hub サービス：スナップショットの読み込みと更新、行の検証と修復、検索とファセット、ISO 3166 テーブル、語彙。
tests/	src/ の構成に対応した、合成フィクスチャを用いるユニットテスト。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックに try/catch は使わないでください。
• ログには ctx.log を、帰属情報、合計、通知には ctx.enrich を使用してください。
• 新しいツールとリソースは、src/index.ts の createApp() 配列に登録してください。
• 外部 API 呼び出しはラップしてください。生データを検証し、ドメイン型に正規化してから、出力スキーマに従って返します。不足しているフィールドを捏造しないでください。

コントリビューション

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

bun run devcheck
bun run test

ライセンス

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