reliefweb-mcp-server

---

概述

来自 ReliefWeb 的人道主义报告、灾害、职位、培训和国家概况。ReliefWeb 是 OCHA 的危机应对信息中心。搜索和阅读 ReliefWeb 的所有内容类型。

工具

工具	描述
reliefweb_search_reports	搜索人道主义报告，可按国家、灾害、格式、主题、语言、来源和日期筛选
reliefweb_get_report	按数字 ID 获取单份报告，包含完整正文和元数据
reliefweb_search_disasters	按类型、国家、状态、GLIDE 编号和日期范围搜索灾害
reliefweb_get_disaster	获取灾害记录，包含概况、关键内容链接、紧急呼吁和响应计划
reliefweb_get_country	按 ISO3 代码获取国家概况，包含概览、紧急呼吁和精选链接
reliefweb_list_countries	列出 ReliefWeb 跟踪的所有国家，可筛选为当前有人道主义局势的国家
reliefweb_search_jobs	搜索人道主义职位，可按国家、组织、职业类别和经验水平筛选
reliefweb_get_job	按数字 ID 获取职位信息，包含完整职位描述和申请说明
reliefweb_search_training	搜索培训，可按形式、国家、职业类别、费用、列表语言或授课语言及日期筛选 — 默认搜索即将开始的培训
reliefweb_get_training	按数字 ID 获取培训信息，包含完整描述、报名说明和费用详情
reliefweb_list_sources	按名称和类型浏览提供内容的组织

资源

资源	描述
reliefweb://reports/{id}	按数字 ID 获取完整报告记录 — 包含元数据、正文和文件 URL。ID 部分只能包含数字
reliefweb://disasters/{id}	按数字 ID 获取灾害记录 — 包含类型、状态、GLIDE、描述和内容链接。ID 部分只能包含数字
reliefweb://countries/{iso3}	按 ISO3 代码获取国家概况 — 包含概览、局势摘要和当前响应计划

提示词

提示词	描述
reliefweb_crisis_briefing	为某个国家或灾害生成结构化的人道主义简报

功能参考

搜索／列表页的上限超过 1,000，以及概况存档的上限超过 100 时，都会被限制到对应上限，并显示请求值和实际应用值。默认值不变：搜索和来源为 10，国家为 100，概况存档为 25。设置 RELIEFWEB_CLAMP_LIMITS=false 可恢复严格的上限验证。始终拒绝零、负数和小数形式的上限。

reliefweb_search_reports _工具

• 全文查询及筛选条件：国家（ISO3）、灾害 ID、格式、主题、语言（ISO 639-1）和来源简称
• 按来源发布日期筛选日期范围（date_from／date_to）— 除完整 ISO 8601 格式外，也可使用 2024-01-15 这样的简写
• 格式为固定集合：News and Press Release、Situation Report、Map、Infographic、Analysis、Other、Assessment、Manual and Guideline、Appeal、UN Document、Evaluation and Lessons Learned — 匹配时忽略大小写、空格和标点；其他值将被拒绝，并显示可用格式列表
• 对于命名参数未涵盖的复合条件，可使用原始 filter 对象
• 通过 offset／limit 分页，每次调用最多 1,000 条（默认 10 条）
• include_archived 不起作用 — 报告不带存档类别，因此所有报告本来就都在范围内

---

reliefweb_get_report _工具

• 完整正文 Markdown、所有元数据和文件附件 URL
• 使用 reliefweb_search_reports 后获取内容 — 正文大小为 10–100KB
• 超出响应预算时改为返回章节大纲；单独设置 sections: ["body"] 可重新获取正文
• ID 不存在时，返回结构化的 not_found

---

reliefweb_search_disasters _工具

• 按灾害类型、国家、状态和 GLIDE 编号筛选，便于跨系统关联
• 按灾害创建日期筛选日期范围（date_from/date_to）——除完整 ISO 8601 格式外，也支持直接使用 2024-01-15
• 状态为固定集合：alert、ongoing、past、alert-archive；多个状态用逗号分隔，匹配时不区分大小写、空格和标点
• 只有设置 include_archived=true 才能获取 alert-archive 记录——默认预设会将其隐藏
• 通过 offset/limit 分页，每次调用最多返回 1,000 条（默认 10 条）
• 返回的 ID 可用于 reliefweb_get_disaster，也可作为 reliefweb_search_reports 中的 disaster_id 筛选条件

---

reliefweb_get_disaster _工具

• 完整描述、概况、受影响国家和 GLIDE 编号
• 可检索已归档和当前的灾害记录
• 三个精选列表——keyContent、appealsResponsePlans、usefulLinks——各自只返回当前有效条目；可通过 archive: { list: <name> } 分页获取已归档条目
• 重大灾害的记录可能达数万 KB；超出响应预算时，记录会缩减为各部分的提纲，可使用 sections: ["description"] 或 ["profileOverview"] 一次获取一个叙述部分
• sections 和 archive 是互斥模式——同时提供两者的调用会被拒绝
• 如果 ID 不存在，会返回结构化的 not_found

---

reliefweb_get_country _工具

• 由 OCHA 编辑整理的局势概况文本
• 三个精选列表——keyContent、appealsResponsePlans、usefulLinks——各自只返回当前有效条目；可通过 archive: { list: <name> } 分页获取已归档条目（长期危机的归档条目可能多达数千条）
• sections 和 archive 是互斥模式——同时提供两者的调用会被拒绝
• 与其他详情工具一样，内容超出响应预算时会返回各部分的提纲；不过，仅含当前有效内容的概况通常较短，很少超出预算
• 使用 reliefweb_list_countries 查找有效的 ISO3 代码
• 未知 ISO3 代码会返回结构化的 not_found

---

reliefweb_list_countries _工具

• 可选设置 crisis_only=true，仅列出正在进行的活跃人道主义局势（状态为 ongoing）
• 返回 ISO3 代码、状态和规范 URL——将 ISO3 代码用于 reliefweb_get_country
• 每次调用最多返回 1,000 条（默认 100 条）

---

reliefweb_search_jobs _工具

• 按国家、组织简称、职业类别、主题和经验级别筛选
• 默认返回当前开放的招聘信息；设置 include_archived=true 可获取已关闭的归档信息，其数量远多于开放职位
• 可按最新发布排序（date.created:desc，默认）或按最早截止时间排序（date.closing:asc）
• 通过 offset/limit 分页，每次调用最多返回 1,000 条（默认 10 条）
• 返回的 ID 可用于 reliefweb_get_job

---

reliefweb_get_job _工具

• 完整职位描述和申请说明——这两项都不会出现在搜索结果中
• 招聘状态、索引日期／截止日期／最后修改日期、招聘组织、国家、职业类别、经验级别和职位类型
• 提供两个规范 URL（易读别名和节点 URL）
• 可获取已过期和开放的招聘信息
• 超出响应预算时会返回各部分的提纲；使用 sections: ["howToApply"] 可在不获取完整职位描述的情况下提取申请说明
• 返回结构化的 not_found，并指向 reliefweb_search_jobs

---

reliefweb_search_training _tool

• 按国家、来源、形式（on-site 或 online）、职业类别和费用（free 或 fee-based）筛选
• language 筛选列表语言；training_language 筛选授课语言。组织方提供费用和授课语言信息时，摘要会包含这些内容
• 按培训开始日期筛选日期范围（date_start_from/date_start_to）——单独使用 2024-06-01 即可，也支持完整的 ISO 8601 格式
• 未指定任一日期边界时，搜索范围限定为从现在起开始的培训；指定任一边界即可设定明确范围，包括历史范围
• include_archived=true 会纳入已结束的列表，并取消“从现在起开始”的默认范围，因此未设置日期边界的搜索会覆盖全部记录
• 默认按最早开始日期排序（date.start:asc，与报告日期字段不同）；可用 sort 覆盖
• 返回供 reliefweb_get_training 使用的 ID

---

reliefweb_get_training _tool

• 完整说明和注册指南——搜索结果不包含这两项
• 费用类别、组织方提供的费用详情，以及组织方自己的活动 URL
• 列表状态、开始／结束／注册／索引日期、主办城市、形式、类型、列表和授课语言、组织来源，以及两个规范 URL
• 可获取已结束和当前的列表
• 若响应超出预算，则返回章节大纲；sections: ["cost", "feeInformation", "howToRegister"] 仅提取实用信息
• 返回结构化的 not_found，指向 reliefweb_search_training

---

reliefweb_list_sources _tool

• 可选按名称文本或组织 type 筛选：Government、International Organization、Non-governmental Organization、Academic and Research Institution、Media、Red Cross/Red Crescent Movement、Other
• 返回简称、类型、组织 URL 和主页 URL
• 使用 offset/limit 分页；每次最多返回 1,000 条（默认 10 条）
• 在 reliefweb_search_reports、reliefweb_search_jobs 和 reliefweb_search_training 的 source 筛选条件中使用 shortname

---

reliefweb://reports/{id} _resource

• 完整报告记录，格式为 application/json——包含元数据、正文文本和文件 URL
• id 必须仅由数字组成，且与搜索结果返回的 ID 完全一致
• 始终返回完整记录——不支持章节选择器；对于过长的报告，请使用 reliefweb_get_report

---

reliefweb://disasters/{id} _resource

• 灾害记录，格式为 application/json——包含类型、状态、GLIDE、描述和精选内容链接
• id 必须仅由数字组成，且与搜索结果返回的 ID 完全一致
• 始终返回完整记录——不支持章节选择器；对于过长的灾害记录或需要分页浏览存档时，请使用 reliefweb_get_disaster

---

reliefweb://countries/{iso3} _resource

• 国家简介，格式为 application/json——包含概览、形势摘要和当前响应计划
• 等同于调用 reliefweb_get_country
• iso3 必须是 3 个字母的 ISO 3166-1 alpha-3 代码

---

reliefweb_crisis_briefing _prompt

• 参数：必填的 country_or_disaster（名称、ISO3 代码或 GLIDE 编号）；可选的 focus——situation、jobs 或 full（默认值）
• 返回一条用户消息，指示 Agent 使用 ReliefWeb 工具收集数据，然后综合整理简报，并引用报告标题和日期
• 在进行筛选调用前，将国家名称解析为 ISO3 代码；灾害名称搜索与 GLIDE 搜索分别进行

reliefweb-guide _skill

随附的指南涵盖国家／灾害研究、机会评估，以及在声称缺少历史资料前应进行的检查。MCP 客户端可将其作为技能资源发现并阅读。

功能

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

ReliefWeb 专属功能：

• 全面支持 ReliefWeb 的六种内容类型：报告、灾害、国家、职位、培训和来源
• 复合筛选器构建器支持 ReliefWeb API v2 的嵌套 AND/OR 条件
• 报告 format、灾害 status 和培训 cost 的词汇匹配会统一大小写、空格和标点，无需严格匹配 ReliefWeb 的拼写
• 日期边界会在本地拒绝不可能的日历日期和时间；有效的日终时间 24:00 会解析为次日午夜
• RELIEFWEB_APP_NAME 会在启动时验证——自 2025 年 11 月起，该 API 要求提供此项
• 每日 1,000 次 API 调用配额，会在每个搜索和列表工具的上游错误恢复文本中显示

便于 Agent 使用的输出：

• 搜索结果默认不包含正文文本——Agent 使用对应的 reliefweb_get_* 工具显式获取正文，以控制上下文预算
• 超大记录会显示大纲而非截断内容，并提供章节选择器以便精确获取所需内容
• 精选资料档案会分页显示而非直接省略，并提供准确的总数，以及仍有更多结果时的下一偏移量
• 提供类型化的 not_found 错误约定；无结果提示会回显已应用的筛选条件，并建议如何放宽条件

开始使用

使用 Claude Code 连接到公开托管服务：

claude mcp add --transport http reliefweb-mcp-server https://reliefweb.caseyjhand.com/mcp

或者，使用你自己的预先批准的 ReliefWeb appname 在本地运行：

claude mcp add reliefweb-mcp-server -e RELIEFWEB_APP_NAME=your-app-name -- npx -y @cyanheads/reliefweb-mcp-server

对于其他 MCP 客户端，请将以下内容添加到 MCP 客户端配置文件中：

{
  "mcpServers": {
    "reliefweb-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/reliefweb-mcp-server"],
      "env": {
        "RELIEFWEB_APP_NAME": "your-app-name"
      }
    }
  }
}

在 ReliefWeb API 注册 appname。Docker 或从源代码构建的相关说明，请参阅运行服务。

配置

变量	描述	默认值
RELIEFWEB_APP_NAME	必填。 ReliefWeb API v2 预先批准的 appname。请访问 reliefweb.int/help/api 注册。	—
RELIEFWEB_CLAMP_LIMITS	将超出上限的页面限制调整至上限，并显示明确提示。设为 false 可恢复严格的架构最大值限制。	true
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http	stdio
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_HTTP_ENDPOINT_PATH	挂载 MCP 服务的 HTTP 端点路径	/mcp
MCP_PUBLIC_URL	用于由 TLS 终止反向代理部署的公开来源覆盖值	无
MCP_AUTH_MODE	身份验证：none、jwt 或 oauth	none
MCP_SESSION_MODE	HTTP 会话处理方式：stateless、stateful 或 auto（解析为 stateful）。服务在 src/index.ts 中声明为 stateless——无需任何处理程序使用会话，因此仅在需要覆盖时设置此项。	stateless
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）	info
MCP_GC_PRESSURE_INTERVAL_MS	选择启用的、仅限 Bun 的强制 GC 压力循环（毫秒）。如果持续 HTTP 负载下出现堆增长，可尝试设为 60000。	0（已禁用）
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
OTEL_ENABLED	启用 OpenTelemetry	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

需要 Bun v1.4.0 或更高版本（或者使用已构建的服务时需要 Node.js v24+）。

git clone https://github.com/cyanheads/reliefweb-mcp-server.git
cd reliefweb-mcp-server && bun install
cp .env.example .env   # set RELIEFWEB_APP_NAME

• 构建并运行生产版本：

  # 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
  

Docker

docker run --rm -e RELIEFWEB_APP_NAME=your-app-name -p 3010:3010 ghcr.io/cyanheads/reliefweb-mcp-server:latest

镜像默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/reliefweb-mcp-server。若要使用 stdio，请运行 docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio -e RELIEFWEB_APP_NAME=your-app-name ghcr.io/cyanheads/reliefweb-mcp-server:latest。使用 docker build -t reliefweb-mcp-server . 在本地构建；默认会安装 OpenTelemetry 对等依赖，若要省略这些依赖，请添加 --build-arg OTEL_ENABLED=false。

项目结构

目录	用途
src/mcp-server/tools	工具定义（*.tool.ts）。涵盖报告、灾害、国家、工作、培训和来源的 11 个工具，以及共享的分页、章节大纲和档案资料辅助工具。
src/mcp-server/resources	资源定义。报告、灾害和国家资源。
src/mcp-server/prompts	提示词定义。危机简报提示词。
src/services/reliefweb	ReliefWeb API 服务层——HTTP 客户端、筛选器构建器，以及六种内容类型的响应规范化器。
src/config	使用 Zod 解析和验证服务专用环境变量。
skills/	已发布的 Agent 指南，同时作为 MCP 技能资源提供。
tests/	单元测试和集成测试，结构与 src/ 相对应。

开发指南

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

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 在 createApp() 数组中注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参见 LICENSE。