
reliefweb-mcp-server
io.github.cyanheads/reliefweb-mcp-server
Search ReliefWeb humanitarian reports, disasters, jobs, training, and country profiles via MCP.
Documentation
@cyanheads/reliefweb-mcp-server
Search ReliefWeb humanitarian reports, disasters, jobs, training, and country profiles via MCP. STDIO or Streamable HTTP.
Public Hosted Server: https://reliefweb.caseyjhand.com/mcp
Overview
Humanitarian reports, disasters, jobs, training, and country profiles from ReliefWeb, OCHA's information hub for crisis response. Search and read across every ReliefWeb content type.
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 by format, country, career category, cost, listing or delivery language, 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
Search/list page limits above 1,000 and profile-archive limits above 100 are clamped with a notice showing the requested and applied values. Defaults are unchanged: 10 for searches and sources, 100 for countries, 25 for profile archives. Set RELIEFWEB_CLAMP_LIMITS=false to restore strict upper-bound validation. Zero, negative, and fractional limits are always rejected.
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 bare2024-01-15works 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
filterobject for compound conditions the named params don't cover - Pagination via
offset/limit, up to 1,000 per call (default 10) include_archivedhas no effect — reports carry no archived class, so every report is already in scope
reliefweb_get_report tool
- Full body Markdown, all metadata, and file attachment URLs
- Use after
reliefweb_search_reportsto 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_foundwhen 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 bare2024-01-15works 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-archiveis reachable only withinclude_archived=true— the default preset hides it- Pagination via
offset/limit, up to 1,000 per call (default 10) - Returns IDs for
reliefweb_get_disasterand as thedisaster_idfilter inreliefweb_search_reports
reliefweb_get_disaster tool
- Full description, profile overview, affected countries, and GLIDE number
- Retrieves archived disaster records as well as current ones
- Three curated lists —
keyContent,appealsResponsePlans,usefulLinks— each returns only its currently-active entries; archived entries page viaarchive: { 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 sectionsandarchiveare alternative modes — a call supplying both is rejected- Returns structured
not_foundwhen 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 viaarchive: { list: <name> } sectionsandarchiveare 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_countriesto discover valid ISO3 codes - Returns structured
not_foundfor an unknown ISO3 code
reliefweb_list_countries tool
- Optional
crisis_only=trueto 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=truereaches 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_foundpointing back atreliefweb_search_jobs
reliefweb_search_training tool
- Filtering by country, source, format (
on-siteoronline), career category, and cost (freeorfee-based) languagefilters the listing language;training_languagefilters delivery language. Summaries include cost and delivery languages when supplied by the organizer- Date range filtering on training start date (
date_start_from/date_start_to) — a bare2024-06-01works 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=truereaches 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 withsort - 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_foundpointing back atreliefweb_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
shortnamewith thesourcefilter inreliefweb_search_reports,reliefweb_search_jobs, andreliefweb_search_training
reliefweb://reports/{id} resource
- Full report record as
application/json— metadata, body text, and file URLs idmust be digits only, exactly as search returned it- Always returns the whole record — no section selector; use
reliefweb_get_reportfor an oversized report
reliefweb://disasters/{id} resource
- Disaster record as
application/json— type, status, GLIDE, description, and curated content links idmust be digits only, exactly as search returned it- Always returns the whole record — no section selector; use
reliefweb_get_disasterfor 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 iso3must be a 3-letter ISO 3166-1 alpha-3 code
reliefweb_crisis_briefing prompt
- Arguments:
country_or_disasterrequired (name, ISO3 code, or GLIDE number);focusoptional —situation,jobs, orfull(default) - Returns one user message instructing the agent to gather data with the ReliefWeb tools, then synthesize a briefing citing report titles and dates
- Resolves country names to ISO3 codes before filtered calls; keeps disaster-name and GLIDE searches separate
reliefweb-guide skill
The bundled guide covers country/disaster research, opportunity evaluation, and checks before claiming that historical material is absent. MCP clients can discover and read it as a skill resource.
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 report
format, disasterstatus, and trainingcostnormalizes case, spacing, and punctuation instead of requiring exact ReliefWeb spelling - Date bounds reject impossible calendar dates and times locally; valid end-of-day
24:00resolves to the next midnight RELIEFWEB_APP_NAMEvalidated 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_founderror contracts and empty-result notices that echo applied filters and suggest how to broaden
Getting started
Connect to the public hosted server with Claude Code:
claude mcp add --transport http reliefweb-mcp-server https://reliefweb.caseyjhand.com/mcp
Or run locally with your own pre-approved ReliefWeb appname:
claude mcp add reliefweb-mcp-server -e RELIEFWEB_APP_NAME=your-app-name -- npx -y @cyanheads/reliefweb-mcp-server
For other MCP clients, add this to your MCP client configuration file:
{
"mcpServers": {
"reliefweb-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/reliefweb-mcp-server"],
"env": {
"RELIEFWEB_APP_NAME": "your-app-name"
}
}
}
}
Register an appname at ReliefWeb API. For Docker or a source build, see Running the server.
Configuration
| Variable | Description | Default |
|---|---|---|
RELIEFWEB_APP_NAME | Required. Pre-approved appname for the ReliefWeb API v2. Register at reliefweb.int/help/api. | — |
RELIEFWEB_CLAMP_LIMITS | Clamp over-cap page limits with an explicit notice. false restores strict schema maxima. | true |
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
Requires Bun v1.4.0 or higher (or Node.js v24+ for the built server).
git clone https://github.com/cyanheads/reliefweb-mcp-server.git
cd reliefweb-mcp-server && bun install
cp .env.example .env # set RELIEFWEB_APP_NAME
-
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 run --rm -e RELIEFWEB_APP_NAME=your-app-name -p 3010:3010 ghcr.io/cyanheads/reliefweb-mcp-server:latest
The image defaults to HTTP transport, stateless session mode, and logs to /var/log/reliefweb-mcp-server. For stdio, use docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio -e RELIEFWEB_APP_NAME=your-app-name ghcr.io/cyanheads/reliefweb-mcp-server:latest. Build locally with docker build -t reliefweb-mcp-server .; OpenTelemetry peers are installed by default — add --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. |
skills/ | Published agent guidance, also served as MCP skill resources. |
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/catchin tool logic - Use
ctx.logfor logging,ctx.statefor 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.
@cyanheads/reliefweb-mcp-servernpm install @cyanheads/reliefweb-mcp-server@cyanheads/reliefweb-mcp-servernpm install @cyanheads/reliefweb-mcp-serverRemote
Related Servers
io.github.cyanheads/anime-mcp-server
Search anime/manga, franchise relations, schedule, characters, rankings, studio filmography.
io.github.cyanheads/art-institute-chicago-mcp-server
Search the Art Institute of Chicago collection: artworks, artists, exhibitions, and audio guides.
io.github.cyanheads/arxiv-mcp-server
Search arXiv, fetch paper metadata, and read full-text content.