unesco-heritage-mcp-server

---

概述

UNESCO 世界遗产名录、非物质文化遗产名录、生物圈保护区和世界地质公园。搜索并读取完整记录、查看《濒危世界遗产名录》，还可以查找任意地点附近的遗产地、保护区或地质公园。无需 API 密钥。

工具

工具	描述
unesco_search_sites	按关键词、国家、类别、地区、标准、列入年份、濒危名录或跨境状态，或距某点的距离搜索世界遗产地
unesco_get_site	获取遗产地的完整记录：突出的普遍价值声明、标准及其含义、组成部分、坐标和图片署名
unesco_search_intangible_heritage	按关键词、国家、名录、列入年份、跨国状态或关联的世界遗产地搜索三份非物质遗产名录
unesco_get_intangible_heritage_element	获取某项遗产的完整记录：描述、名录、国家、概念术语、关联遗产地和图片署名
unesco_search_biosphere_reserves	按关键词、国家、地区、MAB 区域网络、指定年份、跨境或 SIDS 状态，或距某点的距离搜索生物圈保护区
unesco_get_biosphere_reserve	获取保护区的完整记录：生态和社会经济概况、分区面积及人口、审查年份和坐标
unesco_search_geoparks	按关键词、国家、指定年份、跨国状态或距某点的距离搜索 UNESCO 世界地质公园
unesco_get_geopark	获取地质公园的完整记录：简介、描述、关于支持当地社区的说明、记录的面积和人口，以及坐标
unesco_list_reference	解读标准、国家（名称转为 ISO 代码）、地区、非物质遗产名录和 MAB 网络；报告数据集覆盖范围和数据日期

资源

资源	描述
unesco://site/{id_no}	一条世界遗产地记录
unesco://intangible-heritage/{ich_ref}	一条非物质遗产项目记录
unesco://biosphere-reserve/{mab_id}	一条生物圈保护区记录
unesco://geopark/{ugg_id}	一条 UNESCO 世界地质公园记录

每项资源都与对应的获取工具相对应。

功能参考

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、radius_km，上限为 5000，默认值为 100）；通过遗产地的代表点或其任一组成部分进行匹配
• 每页最多返回 50 个遗产地（默认值为 20；如果 limit 值较大且不超过 10,000，则按 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 查询一个遗址：可使用数字、数字字符串或遗址的 whc.unesco.org 页面 URL；max_components 列出最多 1000 个组成部分（默认 20；若设置更大的值，最高为 10,000，则实际返回 1000 个，并在 notice 中说明）
• 描述、突出普遍价值声明、带有含义和 source: "recorded" | "inferred" 的 criteria[]、附 ISO 代码的缔约国、坐标、面积、secondary_years、濒危名录年份、六种语言的名称，以及附有署名的主 image
• description_language（en、fr、es、ru、ar、zh）会以该语言返回 UNESCO 的描述，并在 description_language 中标明该语言；若 UNESCO 未发布该语言的描述，则返回英文描述，description_language 为 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
• 每页最多 50 个项目（默认 20；若 limit 设置为更大的值，最高为 10,000，则实际返回 50 个，并在 notice 中说明）；使用 next_cursor 获取后续结果；结果行不包含描述，但会提供主要 concepts 和关联的 world_heritage_sites
• facets 包含名录、多国状态、排名前 10 的国家和排名前 10 的概念词

---

unesco_get_intangible_heritage_element _工具

• 按 ich_ref 查询一个项目：可使用数字、数字字符串或项目的 ich.unesco.org 页面 URL
• 描述、名录、国家、列入年份、主要和次要 concepts、关联的 world_heritage_sites、UNESCO 页面，以及附有说明文字和署名的主 image；未知引用编号会报错 element_not_found
• description_language: "fr" 会返回 UNESCO 的法文描述（UNESCO 仅发布英文和法文版本），若无法提供法文，则会像 unesco_get_site 一样回退到英文并附带 notice

---

unesco_search_biosphere_reserves _工具

• 筛选条件：query（名称、简介以及生态或社会经济相关文本；没有生物群系字段，因此请搜索栖息地相关词语）、country、region、regional_network（名称或缩写）、transboundary、sids、designated_from / designated_to，以及 near
• 每页最多 50 个保护区（默认 20；若 limit 设置为更大的值，最高为 10,000，则实际返回 50 个，并在 notice 中说明）；使用 next_cursor 获取后续结果；sort 可设为 relevance、name、designated_newest、designated_oldest、area_largest 或 distance；设为 include_description: false 时，结果行不包含简介
• 跨境保护区会按参与国各显示一次，每个条目都有自己的 mab_id；facets 包含地区、区域网络、跨境和 SIDS 状态，以及排名前 10 的国家

---

unesco_get_biosphere_reserve _工具

• 按 mab_id 查询一个保护区，匹配时不区分大小写或重音符号
• 简介、生态和社会经济特征、各分区的陆地和海洋面积、各分区人口、指定年份、扩展、改名和定期审查年份、坐标、网站以及 UNESCO 页面
• 面积（公顷）和人口数据按记录原样返回：各分区面积之和可能与总面积不同；人口值 0 可能表示无人居住，也可能表示未报告；未知 ID 会报错 biosphere_reserve_not_found

---

unesco_search_geoparks _工具

• 筛选条件：query（名称、简介、描述和社区账号；可搜索 volcanic 或 karst 等地貌词）、country、transnational、designated_from / designated_to，以及 near（按各地质公园的一个坐标点测量距离）
• 每页最多 50 个地质公园（默认 20；若 limit 更大、最高为 10,000，则仍按 50 个返回，并在 notice 中说明）；使用 next_cursor 继续翻页；sort 可设为 relevance、name、designated_newest、designated_oldest、area_largest 或 distance；include_description: false 会省略列表项简介
• 跨国地质公园在一行中列出其所有国家；facets 涵盖跨国状态和排名前 10 的国家；若年份范围的起始年份不晚于 2015 年，则会添加一条 notice，说明在该认定制度设立前获得认定的地质公园均标注为 2015 年

---

unesco_get_geopark _工具

• 按 ugg_id 获取一个地质公园（例如 EUFR10），大小写不限
• 返回记录中的国家、认定年份、跨国状态、面积和人口（若 UNESCO 未记录人口，则不返回 population）、坐标、简介、描述、支持当地社区的相关说明、网站和 UNESCO 页面；未知 ID 会报错 geopark_not_found

---

unesco_list_reference _工具

• topic：criteria、countries、regions、intangible_lists、biosphere_networks 或 datasets
• filter 保留匹配的行；对于 countries，输入国家名称、ISO 代码或常见的旧称，会返回每个 country 输入可接受的代码，以及该国的遗产地、非物质文化遗产项目、生物圈保护区和地质公园数量
• datasets 会报告各数据集的记录数、data_as_of、许可证、署名说明和覆盖范围备注

---

unesco://site/{id_no} _资源

• 以 application/json 格式返回 unesco_get_site 记录（最多包含 20 个组成部分；完整数量由 components_total 提供）和英文描述，以及 sources；id_no 来自 unesco_search_sites

---

unesco://intangible-heritage/{ich_ref} _资源

• 以 application/json 格式返回 unesco_get_intangible_heritage_element 记录和英文描述，以及 sources；ich_ref 来自 unesco_search_intangible_heritage

---

unesco://biosphere-reserve/{mab_id} _资源

• 以 application/json 格式返回 unesco_get_biosphere_reserve 记录和 sources；mab_id 来自 unesco_search_biosphere_reserves，包含非 ASCII 字母时需进行百分号编码

---

unesco://geopark/{ugg_id} _资源

• 以 application/json 格式返回 unesco_get_geopark 记录和 sources；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（UNESCO 世界地质公园）均会在首次使用时加载为内存快照（需要两次上游请求），并每隔 24 小时刷新一次；搜索、分面和距离计算均在本地执行，刷新失败时会继续提供上一个快照
• 上游流量限制为最多两个并发请求、每天最多 200 次请求；收到 429 响应后会进入冷却期，并遵循 Retry-After
• UNESCO 的标准字段未涵盖标准（vi），因此会根据每个遗产地的突出普遍价值声明推断该标准，并在其出现的所有位置标注为推断值
• 国家输入接受任意大小写的 ISO 3166-1 alpha-2 或 alpha-3 代码，并匹配该国参与的所有跨国遗产地、多国共同申报项目或跨国地质公园；遗产地和项目 ID 也接受对应的 UNESCO 页面 URL

适合 Agent 使用的输出：

• 每个响应均包含来源信息：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 会标记为可重试（retryable），并提供 retryAfter；若 Data Hub 拒绝请求，或返回服务器无法使用的数据，则会标记为不可重试

数据与许可

所有四个数据集均来自 UNESCO Data Hub，并采用 CC BY-SA 4.0 许可。重用数据时请注明 UNESCO；每个响应中的 sources 块都包含可直接使用的署名信息。在相同方式共享条款下，改编后的数据必须采用相同许可证共享。

图片不受该许可证涵盖。每张世界遗产和非物质文化遗产图片均保留其自身版权，版权方和摄影师信息会随图片记录一同提供。该服务会返回图片链接，但绝不会获取或代理图片。

本服务是独立项目，与 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	每个数据集对应一个记录资源。
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 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不捏造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。