unhcr-refugees-mcp-server

---

概述

难民和流离失所统计数据来自 UNHCR Refugee Data Finder：自 1951 年以来的难民、寻求庇护者、境内流离失所者（IDP）和无国籍人口数据；自 2000 年以来的庇护申请和决定数据；以及自 1959 年以来的回返和重新安置数据。按原籍国和庇护国提取年度数据，并对大型结果运行 SQL。无需 API 密钥。

工具

工具	描述
unhcr_list_reference	解码国家（ISO3、ISO2 和 UNHCR 代码、名称、地区）、区域局、数据集覆盖年份、人口类型和庇护代码
unhcr_get_population	自 1951 年起，按原籍国和／或庇护国统计的年末流离失所存量，同时提供 UNRWA 和 IDMC 序列，以及可选的当年即时预测
unhcr_get_demographics	自 2001 年起，按人口类型、性别和年龄段统计的年末存量，并提供 UNHCR 可细分统计的人口占比
unhcr_get_asylum_applications	自 2000 年起按年统计的庇护申请，默认按申请阶段细分
unhcr_get_asylum_decisions	自 2000 年起按年统计的庇护决定及其结果，并提供难民认定率和总体保护率
unhcr_get_solutions	自 1959 年起按年统计的难民返乡、安置、归化和 IDP 返乡情况
unhcr_dataframe_describe	按名称描述已暂存的数据框；若启用了列表功能，则可列出全部数据框，并提供来源、过期时间、完整性和列架构
unhcr_dataframe_query	对已暂存的数据框运行一条只读 SQL SELECT，并可选择将结果另存为新数据框
unhcr_dataframe_drop	在 TTL 到期前删除已暂存的数据框；默认选择加入，且不会出现在 tools/list 中

只有在 UNHCR_DATAFRAME_DROP_ENABLED=true 时才会注册 unhcr_dataframe_drop；其他八种工具始终会公布。

数据框工作流

1. 如果某次 unhcr_get_* 调用的完整结果超过 limit，或者设置了 stage: true，系统就会将所有行暂存为 df_XXXXX_XXXXX 表，并在 dataset 中返回其句柄。
2. unhcr_dataframe_describe 会列出已暂存的表及其列、来源调用和过期时间。使用 MCP_AUTH_MODE=none 时，HTTP 模式下会关闭列表功能，因此需要使用 dataset 中的名称逐个描述表。
3. unhcr_dataframe_query 会跨这些表运行一条只读 DuckDB SELECT；register_as 会将结果保存为新表，以供下一次查询使用。
4. 表会在 UNHCR_DATASET_TTL_SECONDS 指定的时间后过期（默认 24 小时）。设置 UNHCR_DATAFRAME_DROP_ENABLED=true 后，unhcr_dataframe_drop 可以提前删除表。当某个租户暂存的行数超过 1,000,000 时，系统会优先逐出最早的表；导致总数超限的调用会在 evicted 中列出这些表。

数据框使用 DuckDB 的原生绑定，npm 和 Docker 安装包都包含该绑定。Claude Desktop .mcpb 包未包含该绑定，因此其中的数据工具只会以内联方式返回结果。在任何环境中设置 CANVAS_PROVIDER_TYPE=none 都可以关闭数据框功能。

功能参考

五种 unhcr_get_* 工具共用同一套约定：

• 范围： origin 和 asylum 接受 ISO3 代码，大小写不敏感；每个参数可使用字符串或列表，最多各 50 个代码。ISO2 代码会转换为 ISO3；UNHCR 自有代码和国家名称不予接受。每个列出的代码都会返回各自的行；未指定的维度会汇总为一行，除非 expand（origin、asylum 或 both）列出了所有国家。year_from / year_to 默认使用数据集的年份范围，并会限制在该范围内。
• 行： 完整结果按 sort_by 排序，然后截取至 limit（默认 100）。接受 1 至 1,000,000 的请求；超过 500 的值会限制为 500，即使结果为空或较少，也会披露请求值和实际生效的限制。启用数据框后，较大结果的完整数据集会被暂存；stage: true 也会暂存符合限制的结果。
• 输出： total_rows、complete（当 UNHCR_MAX_ROWS 导致获取提前停止时为 false）、measure（stock 或 flow）、applied_scope、latest_year、暂存时的 dataset、data_notes 和 attribution。
• 错误： unknown_country_code、invalid_year_window、year_out_of_coverage、conflicting_scope，以及可重试的 upstream_busy；后者会附带 retryAfter。

---

unhcr_list_reference _工具

• topic：countries、regions、coverage、population_types 或 asylum_codes。选择 countries 时，name_contains 会筛选名称包含所有给定词语的国家，或 ISO3、ISO2 或 UNHCR 代码与其中一个相符的国家；不进行模糊匹配
• coverage 会提供每个数据集的 first_year、latest_year 和 measure，以及当前 nowcast 的月份
• 国家、地区和覆盖范围来自实时 API，并缓存 24 小时；人口类型和庇护代码为静态数据；对于 UNHCR 方法未定义的庇护代码，会标记 documented: false

---

unhcr_get_population _工具

• 年末存量包括 refugees、asylum_seekers、oip、idps、stateless、ooc 和 hst；returned_refugees 和 returned_idps 则是年内流量。sort_by 可接受其中任一项或 year
• unrwa_refugees（在 UNRWA 登记的巴勒斯坦难民）和 idmc_conflict_idps（IDMC 的冲突导致的境内流离失所者估算值）会在对应序列存在时与该行并列显示，绝不会计入 UNHCR 的统计值。也会返回匹配的 UNHCR footnotes，最多 20 条，并提供 footnotes_total
• include_nowcast: true 会附加 UNHCR 对当前年份按庇护国统计的难民和寻求庇护者月度估算值；当 origin 列出代码时则会跳过

---

unhcr_get_demographics _工具

• population_types 可筛选 REF、ASY、OIP、IDP、STA、OOC、HST、RET 或 RDP；sort_by 可接受 year 或 total
• 每行对应一种人口类型，包含 total、14 个性别 × 年龄段（female_0_4 … female_60_plus、female_unknown_age、female_total 及对应的 male_* 字段）、disaggregated 和 sex_disaggregated_share（0–1）。UNHCR 未提供细分数据的年龄段为 null
• 总数来自单独的数据集，因此不一定与 unhcr_get_population 一致；也会像在人口数据中一样返回匹配的 footnotes

---

unhcr_get_asylum_applications _工具

• split_by 指定将 authority、stage 和 decision_level 中的哪些维度分列显示（默认值为 ["stage"]；[] 表示每年、范围和单位只显示一个总计）。求和前会按 stages 筛选，例如 ["N"] 表示新申请；sort_by 可接受 year 或 applied
• 每行会列出汇总其中的 authorities、stages 和 decision_levels 代码、unit（persons 或 cases）以及 applied。案件数绝不会与人数相加

---

unhcr_get_asylum_decisions _工具

• split_by 指定将 authority 和 decision_level 中的哪些维度分列显示（默认值为 []，即全部汇总，符合 UNHCR 计算比率的方式）。求和前会按 decision_levels 筛选，例如 ["FI"] 表示一审
• 每行包含 recognized、complementary_protection、rejected、otherwise_closed、total_decisions、substantive_decisions 和 unit，以及以实质性决定数为分母的百分比 refugee_recognition_rate 和 total_protection_rate。分母为 0 或 null 时，比率为 null
• sort_by 可接受 year 或某项数量（total_decisions、substantive_decisions、recognized、rejected）；无法按比率排序

---

unhcr_get_solutions _工具

• 流量包括 returned_refugees、resettlement、naturalisation 和 returned_idps；sort_by 可接受其中任一项或 year。也会像在人口数据中一样返回匹配的 footnotes
• 不同列中的庇护国含义各异：难民返回的国家、他们被重新安置到的国家，以及授予他们国籍的国家。境内流离失所者的返乡数据则归于其原籍国本身

---

unhcr_dataframe_describe _工具

• 可选的 name（df_XXXXX_XXXXX）；省略后会按新到旧的顺序列出所有暂存表。通过 HTTP 且 MCP_AUTH_MODE=none 时，列表功能处于关闭状态，必须提供 name
• 每个条目包含 source_tool、query_params、created_at、expires_at、row_count、complete、incomplete_sources、providers 和 column_schema。已保存的后代表会在其祖先过期或被移出后保留原始不完整来源句柄。暂存表会添加 origin_unhcr_region、origin_unsd_region、asylum_unhcr_region 和 asylum_unsd_region 列，而内联行中不包含这些列

---

unhcr_dataframe_query _工具

• sql 是一条 DuckDB SELECT 语句，长度最多为 20,000 个字符；支持联接、聚合、窗口函数和 CTE。写入操作、DDL、PRAGMA、ATTACH、文件引用、外部数据函数、引擎内省（current_setting、current_schema、current_schemas、in_search_path）、动态表查找（query_table）和系统目录都会被拒绝，并返回类型化原因。query() 只接受单个 SQL 字符串字面量，并由同一安全检查机制校验
• row_limit（1–10,000，默认值为 1,000）限制查询物化的行数，row_count_capped 标记结果是否达到上限。preview 会以内联形式返回更少的行；register_as 会将结果以新的 df_XXXXX_XXXXX 名称保存，并赋予新的 TTL。该结果计入 1,000,000 行的暂存预算，若结果本身超过此上限，则 register_as 会失败，并返回 register_as_too_large
• SUM 和 COUNT 的值以字符串（BIGINT）形式返回。attribution 会注明 SQL 读取的每个表所含第三方系列的来源
• preview 接受 0–1,000,000，并限制为不超过 row_limit，同时披露请求值和生效值。设为 0 时仍不返回预览行。complete 和 incomplete_sources 描述的是上游覆盖情况，不受显示截断影响：如果原始来源不完整，聚合、联接和已保存的后代表仍会是不完整的
• 序列化后的工具结果（包括两个响应面和通知）总计不超过 65,536 个 UTF-8 字节。超出大小限制时会以一致的方式省略整行或过大的元数据；不会截断值。result_chunks 标识按租户限定的快照，其中包含物化的列、行和结果元数据。快照具有常规 TTL，并计入暂存预算；result_storage_unavailable 表示无法保留该快照。已保存的 register_as 表仍可用

对于 result_chunks.name（例如 df_ABCDE_12345），每次调用读取一个块：

SELECT chunk_index,chunk FROM df_ABCDE_12345 WHERE chunk_index=0

将索引递增，直到 result_chunks.chunk_count - 1。分别对每个块进行 Base64 解码（每块最多包含 6,144 个源字节），按索引顺序拼接解码后的字节，然后解码为 UTF-8 并解析 JSON。字节边界可能会拆开 Unicode 字符，因此应在拼接字节后再解码 UTF-8。快照包含 row_limit 范围内已物化的行，包括被 preview 隐藏的行；row_count_capped 仍表示有其他符合条件的行未被物化。若要获取完整的已注册结果，请查询 registered_as。较小的标量结果使用 Markdown 表格；需要精确保留空白、控制字符、嵌套结构或 Markdown 语法的值则使用围栏式 JSON。

---

unhcr_dataframe_drop _工具

• name（df_XXXXX_XXXXX）；如果没有匹配项，则返回 dropped: false，因此可安全地重复调用
• 仅在 UNHCR_DATAFRAME_DROP_ENABLED=true 时注册；否则，暂存表会由各自的 TTL 回收

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、结构化日志记录，并可选择启用 OpenTelemetry 跟踪。

UNHCR 专属功能：

• 无需密钥的客户端，用于访问 UNHCR Refugee Data Finder 背后的 API（api.unhcr.org/population/v1）。该 API 会忽略未知参数和单独的年份边界，而不是拒绝请求，因此服务端只发送允许列表中的参数，始终成对发送年份边界，并固定使用 ISO3 国家匹配（cf_type=ISO）
• 共享请求队列：按节奏启动请求（UNHCR_REQUESTS_PER_SECOND），最多两个并行请求，收到 429 后进入冷却期，将相同请求合并为一个请求，提供响应缓存，并为每次调用设置 45 秒预算
• 按照 UNHCR 的方式解读数据：明确标注存量和流量；将 UNHCR 的 "-" 返回为 null，而不是零；绝不将个案数与人数相加；认可率以 UNHCR 的实质性决定数为分母计算
• UNHCR 会将低于 5 的数量（庇护决定低于 10）四舍五入到最接近的 5 的倍数，因此小数值为近似值
• 每项包含 UNHCR 数据的结果都会注明来源为“UNHCR Refugee Population Statistics Database”（CC BY 4.0），并附上 UNHCR 的数据集使用条款链接。UNRWA 和 IDMC 数据是这些提供方自身的数据系列，经由 UNHCR API 传递；只要结果中出现这些数据，attribution.providers 就会注明相应提供方，因为其自身条款可能适用

便于 Agent 使用的输出：

• 每项数据结果都包含来源信息：applied_scope 会回显实际发送的代码、年份范围和 ISO2 改写结果，并包含 latest_year、measure、complete 和 attribution
• 将注意事项作为数据返回：data_notes 说明如何解读每项结果（存量或流量、舍入方式、null 的含义），并附上匹配的 UNHCR footnotes 和 rows_matched
• 提供带恢复提示的类型化故障：unknown_country_code 会根据 UNHCR 代码建议对应的 ISO3 代码；year_out_of_coverage 会说明数据集的年份范围；upstream_busy 会提供 retryAfter
• 不会静默删减内容：年份范围调整、空结果提示、截断信息，以及完整数据集的暂存位置，都会作为通知一并返回

开始使用

公共托管实例

可通过 https://unhcr-refugees.caseyjhand.com/mcp 使用公共实例，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

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

托管实例的所有调用方共用一个 UNHCR 请求队列和一个 dataframe 工作区，因此 unhcr_dataframe_describe 在此处需要表的准确名称；不提供列表功能。

自托管 / 本地部署

将以下内容添加到 MCP 客户端配置文件中。

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

也可以使用 npx（无需 Bun）：

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

或使用 Docker：

{
  "mcpServers": {
    "unhcr-refugees-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/unhcr-refugees-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 密钥或账户：UNHCR 的 API 无需密钥，以下所有变量均为可选项。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/unhcr-refugees-mcp-server.git

2. 进入目录：

cd unhcr-refugees-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# optional: every variable has a working default

配置

变量	描述	默认值
UNHCR_REQUESTS_PER_SECOND	整个进程每秒启动的上游请求数（1–10）。所有 HTTP 实例的调用方共享此限制。	4
UNHCR_MAX_ROWS	单次工具调用获取的上游行数上限（10,000–500,000）。结果超过上限时会截断，并报告 complete: false。	150000
UNHCR_CACHE_MAX_MB	响应缓存容量上限，单位为 MB；设为 0 可禁用。参考数据（国家、地区、覆盖范围、脚注）使用独立缓存，且始终启用。	64
UNHCR_DATASET_TTL_SECONDS	暂存数据框的有效时长，单位为秒（最少 60 秒）。	86400
UNHCR_DATAFRAME_DROP_ENABLED	设为 true 可注册 unhcr_dataframe_drop。	false
CANVAS_PROVIDER_TYPE	数据框引擎：duckdb；设为 none 可关闭数据框。	duckdb
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
  bun run test:live  # Opt-in: re-checks the upstream behaviors the client relies on against api.unhcr.org
  

项目结构

目录	用途
src/index.ts	createApp() 入口：服务说明、工具注册、服务设置。
src/config	使用 Zod 解析并验证服务专属环境变量。
src/mcp-server/tools/definitions	工具定义（*.tool.ts）及注册列表，用于控制是否启用 unhcr_dataframe_drop。
src/mcp-server/tools/shared	数据工具共用的范围输入、输出模式、结果整理和 Markdown 渲染。
src/services/unhcr	UNHCR API 客户端：请求构建器、限速获取、响应缓存、参考数据、规范化、庇护数据汇总、脚注匹配。
src/services/canvas-bridge	对接框架 DataCanvas 的适配器：数据框命名、来源信息、过期管理和只读 SQL 限制。
tests/	与 src/ 结构对应的单元测试，以及 tests/live/ 中选择性运行的实时测试套件。

开发指南

开发指南和架构规则请参见 CLAUDE.md。简要说明：

• 处理程序抛出异常，由框架捕获；工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 在 src/mcp-server/tools/definitions/index.ts 的 buildToolDefinitions() 中注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出模式；切勿编造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

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

数据归 UNHCR 所有，并依据 CC BY 4.0 和 UNHCR 的数据集使用条款发布。本项目独立于 UNHCR，且未获得其认可。