io.github.cyanheads/reliefweb-mcp-server

---

Overview

Humanitarian reports, disasters, jobs, training opportunities, and country profiles from ReliefWeb, OCHA's information hub for crisis response. Search, fetch, and page through all six ReliefWeb content types from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
reliefweb_search_reports	Search humanitarian reports with filtering by country, disaster, format, theme, language, source, and date
reliefweb_get_report	Fetch a single report by numeric ID with full body text and metadata
reliefweb_search_disasters	Search disasters by type, country, status, GLIDE number, and date range
reliefweb_get_disaster	Fetch a disaster record with profile, key content links, appeals, and response plans
reliefweb_get_country	Fetch a country profile by ISO3 code with overview, appeals, and curated links
reliefweb_list_countries	List all countries tracked by ReliefWeb, filterable to active humanitarian situations
reliefweb_search_jobs	Search humanitarian job listings by country, organization, career category, and experience level
reliefweb_get_job	Fetch a job posting by numeric ID with the full vacancy description and application instructions
reliefweb_search_training	Search training and learning opportunities by format, country, career category, and date — upcoming starts by default
reliefweb_get_training	Fetch a training listing by numeric ID with the full description, registration instructions, and cost detail
reliefweb_list_sources	Browse contributing organizations by name and type

Resources

Resource	Description
reliefweb://reports/{id}	Full report record by numeric ID — metadata, body text, and file URLs. The ID segment must be digits only
reliefweb://disasters/{id}	Disaster record by numeric ID — type, status, GLIDE, description, and content links. The ID segment must be digits only
reliefweb://countries/{iso3}	Country profile by ISO3 code — overview, situation summary, and active response plans

Prompts

Prompt	Description
reliefweb_crisis_briefing	Generate a structured humanitarian briefing for a country or disaster

Capability reference

reliefweb_search_reports _tool

• Full-text query plus filters: country (ISO3), disaster ID, format, theme, language (ISO 639-1), and source shortname
• Date range filtering on source publication date (date_from/date_to) — a bare 2024-01-15 works alongside full ISO 8601
• Format is a closed set: News and Press Release, Situation Report, Map, Infographic, Analysis, Other, Assessment, Manual and Guideline, Appeal, UN Document, Evaluation and Lessons Learned — matched ignoring case, spacing, and punctuation; anything else is rejected with the list
• Raw filter object for compound conditions the named params don't cover
• Pagination via offset/limit, up to 1,000 per call (default 10)
• include_archived has no effect — reports carry no archived class, so every report is already in scope

---

reliefweb_get_report _tool

• Full body HTML, all metadata, and file attachment URLs
• Use after reliefweb_search_reports to retrieve content — bodies run 10–100KB
• Over the response budget, returns a section outline instead; sections: ["body"] pulls the body back on its own
• Returns structured not_found when the ID doesn't exist

---

reliefweb_search_disasters _tool

• Filtering by disaster type, country, status, and GLIDE number for cross-system correlation
• Date range filtering on disaster creation date (date_from/date_to) — a bare 2024-01-15 works alongside full ISO 8601
• Status is a closed set: alert, ongoing, past, alert-archive; comma-separate for multiple, matched ignoring case, spacing, and punctuation
• alert-archive is reachable only with include_archived=true — the default preset hides it
• Pagination via offset/limit, up to 1,000 per call (default 10)
• Returns IDs for reliefweb_get_disaster and as the disaster_id filter in reliefweb_search_reports

---

reliefweb_get_disaster _tool

• Full description, profile overview, affected countries, and GLIDE number
• Three curated lists — keyContent, appealsResponsePlans, usefulLinks — each returns only its currently-active entries; archived entries page via archive: { list: <name> }
• Major disasters run to tens of KB; over the response budget the record becomes a section outline, and sections: ["description"] or ["profileOverview"] pulls one narrative at a time
• sections and archive are alternative modes — a call supplying both is rejected
• Returns structured not_found when the ID doesn't exist

---

reliefweb_get_country _tool

• Situation overview text curated by OCHA editors
• Three curated lists — keyContent, appealsResponsePlans, usefulLinks — each returns only its currently-active entries; archived entries (thousands deep for a long-running crisis) page via archive: { list: <name> }
• sections and archive are alternative modes — a call supplying both is rejected
• Carries the same section-outline behavior as the other detail tools, though an active-only profile is small enough that it rarely reaches the budget
• Use reliefweb_list_countries to discover valid ISO3 codes
• Returns structured not_found for an unknown ISO3 code

---

reliefweb_list_countries _tool

• Optional crisis_only=true to limit to active humanitarian situations (status ongoing)
• Returns ISO3 codes, status, and canonical URLs — use ISO3 with reliefweb_get_country
• Pagination up to 1,000 entries per call (default 100)

---

reliefweb_search_jobs _tool

• Filtering by country, organization shortname, career category, theme, and experience level
• Returns current open postings by default; include_archived=true reaches the closed archive, far larger than the open set
• Sortable by newest posting (date.created:desc, default) or soonest closing (date.closing:asc)
• Pagination via offset/limit, up to 1,000 per call (default 10)
• Returns IDs for reliefweb_get_job

---

reliefweb_get_job _tool

• Full vacancy description and application instructions — neither is in search results
• Posting status, indexed / closing / last-modified dates, hiring organization, countries, career category, experience level, and job type
• Both canonical URLs (the readable alias and the node URL)
• Reaches expired postings as well as open ones
• Over the response budget, returns a section outline; sections: ["howToApply"] pulls the instructions without the whole description
• Returns structured not_found pointing back at reliefweb_search_jobs

---

reliefweb_search_training _tool

• Filtering by country, source, format (on-site or online), career category, and language
• Date range filtering on training start date (date_start_from/date_start_to) — a bare 2024-06-01 works alongside full ISO 8601
• Scoped to training starting from now when neither date bound is given; supply either one for an explicit range, including a historical one
• include_archived=true reaches concluded listings and drops the start-from-now default, so an otherwise unbounded search reaches the whole record
• Ordered by soonest start date by default (date.start:asc, distinct from report date fields); override with sort
• Returns IDs for reliefweb_get_training

---

reliefweb_get_training _tool

• Full description and registration instructions — neither is in search results
• Cost class, the organizer's fee detail, and the organizer's own event URL
• Listing status, start / end / registration / indexed dates, host cities, format, type, listing and delivery languages, organizing source, and both canonical URLs
• Reaches concluded listings as well as current ones
• Over the response budget, returns a section outline; sections: ["cost", "feeInformation", "howToRegister"] pulls just the practicalities
• Returns structured not_found pointing back at reliefweb_search_training

---

reliefweb_list_sources _tool

• Optional filtering by name text or organization type: Government, International Organization, Non-governmental Organization, Academic and Research Institution, Media, Red Cross/Red Crescent Movement, Other
• Returns short names, types, organization URLs, and homepage URLs
• Pagination via offset/limit, up to 1,000 per call (default 10)
• Use shortname with the source filter in reliefweb_search_reports, reliefweb_search_jobs, and reliefweb_search_training

---

reliefweb://reports/{id} _resource

• Full report record as application/json — metadata, body text, and file URLs
• id must be digits only, exactly as search returned it
• Always returns the whole record — no section selector; use reliefweb_get_report for an oversized report

---

reliefweb://disasters/{id} _resource

• Disaster record as application/json — type, status, GLIDE, description, and curated content links
• id must be digits only, exactly as search returned it
• Always returns the whole record — no section selector; use reliefweb_get_disaster for an oversized disaster or to page an archive

---

reliefweb://countries/{iso3} _resource

• Country profile as application/json — overview, situation summary, and active response plans
• Equivalent to calling reliefweb_get_country
• iso3 must be a 3-letter ISO 3166-1 alpha-3 code

---

reliefweb_crisis_briefing _prompt

• Arguments: country_or_disaster required (name, ISO3 code, or GLIDE number); focus optional — situation, jobs, or full (default)
• Returns one user message instructing the agent to gather data with the ReliefWeb tools, then synthesize a briefing citing report titles and dates

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.

ReliefWeb-specific:

• Full coverage of all six ReliefWeb content types: reports, disasters, countries, jobs, training, and sources
• Compound filter builder supporting nested AND/OR conditions for the ReliefWeb API v2
• Vocabulary matching for format and status filters normalizes case, spacing, and punctuation instead of requiring exact ReliefWeb spelling
• RELIEFWEB_APP_NAME validated at startup — required by the API since November 2025
• 1,000 calls/day API quota, surfaced in each search and list tool's upstream-error recovery text

Agent-friendly output:

• Body text excluded from search results by design — agents fetch it explicitly with the matching reliefweb_get_* tool to control context budget
• Oversized records outline rather than truncate, with a section selector to retrieve exactly what's needed
• Curated-profile archives are paged rather than dropped, with honest totals and a next offset while more remain
• Typed not_found error contracts and empty-result notices that echo applied filters and suggest how to broaden

Getting started

Prerequisites

• Bun v1.3.2 or higher.
• A pre-approved ReliefWeb appname — register at ReliefWeb API and set RELIEFWEB_APP_NAME. The API has required pre-approved appnames since November 2025; requests without one are rejected.

Public Hosted Instance

A public instance is available at https://reliefweb.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

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

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "reliefweb-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/reliefweb-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "RELIEFWEB_APP_NAME": "your-app-name"
      }
    }
  }
}

Or with npx (no Bun required):

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

Or with Docker:

{
  "mcpServers": {
    "reliefweb-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "RELIEFWEB_APP_NAME=your-app-name",
        "ghcr.io/cyanheads/reliefweb-mcp-server:latest"
      ]
    }
  }
}

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

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 RELIEFWEB_APP_NAME=your-app-name bun run start:http
# Server listens at http://localhost:3010/mcp

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd reliefweb-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env and set RELIEFWEB_APP_NAME

Configuration

Variable	Description	Default
RELIEFWEB_APP_NAME	Required. Pre-approved appname for the ReliefWeb API v2. Register at reliefweb.int/help/api.	—
MCP_TRANSPORT_TYPE	Transport: stdio or http	stdio
MCP_HTTP_PORT	HTTP server port	3010
MCP_HTTP_ENDPOINT_PATH	HTTP endpoint path where the MCP server is mounted	/mcp
MCP_PUBLIC_URL	Public origin override for TLS-terminating reverse-proxy deployments	none
MCP_AUTH_MODE	Authentication: none, jwt, or oauth	none
MCP_SESSION_MODE	HTTP session handling: stateless, stateful, or auto (which resolves to stateful). The server declares stateless in src/index.ts — no handler needs a session — so set this only to override.	stateless
MCP_LOG_LEVEL	Log level (debug, info, warning, error, etc.)	info
MCP_GC_PRESSURE_INTERVAL_MS	Opt-in Bun-only forced-GC pressure loop (ms). Try 60000 if heap growth is observed under sustained HTTP load.	0 (disabled)
LOGS_DIR	Directory for log files (Node.js only).	<project-root>/logs
STORAGE_PROVIDER_TYPE	Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1	in-memory
OTEL_ENABLED	Enable OpenTelemetry	false

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run the production version:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• Run checks and tests:

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

Docker

docker build -t reliefweb-mcp-server .
docker run --rm -e RELIEFWEB_APP_NAME=your-app-name -p 3010:3010 reliefweb-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/reliefweb-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
src/mcp-server/tools	Tool definitions (*.tool.ts). Eleven tools across reports, disasters, countries, jobs, training, and sources, plus the shared pagination, section-outline, and profile-archive helpers.
src/mcp-server/resources	Resource definitions. Report, disaster, and country resources.
src/mcp-server/prompts	Prompt definitions. Crisis briefing prompt.
src/services/reliefweb	ReliefWeb API service layer — HTTP client, filter builder, and response normalizers for all six content types.
src/config	Server-specific environment variable parsing and validation with Zod.
tests/	Unit and integration tests, mirroring the src/ 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, ctx.state for storage
• Register new tools and resources in the createApp() arrays
• 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 devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.