io.github.cyanheads/reliefweb-mcp-server

@cyanheads/reliefweb-mcp-server

Search ReliefWeb humanitarian reports, disasters, jobs, training, and country profiles via MCP. STDIO or Streamable HTTP.

11 Tools • 3 Resources • 1 Prompt

Public Hosted Server: https://reliefweb.caseyjhand.com/mcp

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

Resources

Prompts

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

1. Navigate into the directory:

cd reliefweb-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

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

Configuration

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

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.