unesco-heritage-mcp-server

Overview

Three UNESCO datasets from the UNESCO Data Hub: the World Heritage List, the Intangible Cultural Heritage lists, and the World Network of Biosphere Reserves. Search sites (the List of World Heritage in Danger included), intangible heritage elements, and biosphere reserves; read full records; find sites or reserves near a point; and turn country names into the ISO codes the filters take. Runs as a stdio process or a local Streamable HTTP server, with no API key.

Tools

Resources

Each resource mirrors a get tool, so tool-only clients lose nothing.

Capability reference

unesco_search_sites _tool

• Filters: query, country (ISO 3166-1 alpha-2 or alpha-3), category, region, criteria (every listed criterion required), in_danger, transboundary, inscribed_from / inscribed_to, and near (latitude, longitude, radius_km up to 5000, default 100)
• Up to 50 sites per page (default 20), continued with next_cursor; sort takes relevance, name, inscribed_newest, inscribed_oldest, area_largest, danger_listed_newest, or distance
• in_danger: true is the List of World Heritage in Danger; totalCount and facets (category, region, Danger status, criteria, top 10 countries) cover the whole match, and rows carry matched_in and distance_km when query or near is set

unesco_get_site _tool

• One site by id_no: a number, a digit string, or the site's whc.unesco.org page URL; max_components lists 0–1000 component parts (default 20)
• Description, statement of Outstanding Universal Value, criteria[] with meanings and source: "recorded" | "inferred", States Parties with ISO codes, coordinates, area, secondary_years, Danger-list year, names in six languages, and the main image with its credit
• components_total is UNESCO's count and components_unparsed the entries that could not be read; an unknown id fails as site_not_found

unesco_search_intangible_heritage _tool

• Filters: query, country, list (Representative List, Urgent Safeguarding List, Register of Good Safeguarding Practices; RL / USL / Art18 accepted), multinational, world_heritage_site (an id_no), and inscribed_from / inscribed_to
• Up to 50 elements per page (default 20), continued with next_cursor; rows omit the description and carry primary concepts and linked world_heritage_sites
• facets cover list, multinational status, the top 10 countries, and the top 10 concept terms

unesco_get_intangible_heritage_element _tool

• One element by ich_ref: a number, a digit string, or the element's ich.unesco.org page URL
• Description, list, countries, inscription year, primary and secondary concepts, linked world_heritage_sites, UNESCO page, and the main image with its caption and credit; an unknown ref fails as element_not_found

unesco_search_biosphere_reserves _tool

• Filters: query (name, introduction, and ecological or socio-economic text; there is no biome field, so search habitat words), country, region, regional_network (name or acronym), transboundary, sids, designated_from / designated_to, and near
• Up to 50 reserves per page (default 20), continued with next_cursor; sort takes relevance, name, designated_newest, designated_oldest, area_largest, or distance
• A transboundary reserve appears once per participating country, each with its own mab_id; facets cover region, regional network, transboundary and SIDS status, and the top 10 countries

unesco_get_biosphere_reserve _tool

• One reserve by mab_id, matched without regard to case or accents
• Introduction, ecological and socio-economic characteristics, terrestrial and marine area by zone, population by zone, designation, extension, renaming, and periodic-review years, coordinates, website, and UNESCO page
• Areas (hectares) and populations pass through as recorded: zone sums can differ from totals, and a population of 0 can mean none or unreported; an unknown id fails as biosphere_reserve_not_found

unesco_list_reference _tool

• topic: criteria, countries, regions, intangible_lists, biosphere_networks, or datasets
• filter keeps matching rows; on countries, a country name, an ISO code, or a common former name returns the codes every country input accepts
• datasets reports each dataset's record count, data_as_of, license, attribution line, and coverage notes

unesco://site/{id_no} _resource

• The unesco_get_site record with up to 20 components (components_total carries the full count), plus sources, as application/json
• id_no comes from unesco_search_sites

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

• The unesco_get_intangible_heritage_element record plus sources, as application/json
• ich_ref comes from unesco_search_intangible_heritage

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

• The unesco_get_biosphere_reserve record plus sources, as application/json
• mab_id comes from unesco_search_biosphere_reserves; percent-encode an id that holds non-ASCII letters

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

UNESCO-specific:

• Three UNESCO Data Hub datasets: the World Heritage List (whc001), the Intangible Heritage List (ich001), and the Man and the Biosphere Programme (mab001)
• Each dataset loads on first use as an in-memory snapshot (two upstream requests) and refreshes every 24 hours; searching, facets, and distance run locally, and a failed refresh keeps serving the previous snapshot
• Upstream traffic is paced at two concurrent requests and at most 200 a day, with a cooldown after a 429 that honors Retry-After
• Criterion (vi), which UNESCO's criteria fields omit, is inferred from each site's statement of Outstanding Universal Value and marked as inferred wherever it appears
• Country inputs take ISO 3166-1 alpha-2 or alpha-3 codes in any case and match every transboundary site or multinational element a country takes part in; site and element ids also accept their UNESCO page URLs

Agent-friendly output:

• Attribution on every response: sources names each dataset with its data_as_of date, license, and credit line
• Search results report the whole match: totalCount, facets, and an applied_filters echo of the filters and sort the server ran
• Keyword matching is word-prefix with every word required, and matched_in says which field tier matched; a zero-hit notice names the filter whose removal would match the most records
• Typed error contracts (unknown_country, invalid_year_range, sort_needs_input, cursor_mismatch, *_not_found, snapshot_unavailable with retryAfter) carry a recovery hint naming the next call

Data and licensing

All three datasets come from the UNESCO Data Hub and are licensed CC BY-SA 4.0. Credit UNESCO when you reuse the data; every response's sources block carries a ready-made credit line. Under ShareAlike, adapted data must be shared under the same license.

Images are not covered by that license. Each World Heritage and intangible heritage image keeps its own copyright, and its holder and photographer travel with the image record. The server returns image links but never fetches or proxies them.

This server is an independent project and is not affiliated with or endorsed by UNESCO.

Getting started

Add the following to your MCP client configuration file.

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

Or with npx (no Bun required):

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

Or with 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"]    }  }}

For Streamable HTTP, set the transport and start the server:

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

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• No API key or account: the UNESCO Data Hub is open.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd unesco-heritage-mcp-server

3. Install dependencies:

bun install

4. Configure environment (optional):

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

Configuration

The server has no settings of its own; these framework variables apply.

See .env.example for the common framework overrides.

Running the server

Local development

• Build and run the production version:

  sh

  # One-time buildbun run rebuild
  # Run the built serverbun run start:http# orbun run start:stdio

• Run checks and tests:

  sh

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

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for logging and ctx.enrich for attribution, totals, and notices
• Register new tools and resources in the createApp() arrays in src/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheckbun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.