@cyanheads/reliefweb-mcp-server

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

Tools

9 tools for working with ReliefWeb humanitarian data:

reliefweb_search_reports

Search humanitarian reports on ReliefWeb with rich filtering.

• Full-text search across title, body, and key metadata fields

• Filtering by country (ISO3), disaster ID, format, theme, language, and source organization

• Date range filtering on source publication date

• Raw filter object for compound conditions not covered by named params

• Pagination via offset and limit (up to 1,000 per call)

• Optional include_archived=true for historical research (includes expired and archived content)

• Returns paginated summaries — use reliefweb_get_report to fetch full body text

• Rate limit: 1,000 calls/day

reliefweb_get_report

Fetch a single ReliefWeb report by its numeric ID with full body text.

• Full body HTML, all metadata, and file attachment URLs

• Use after reliefweb_search_reports to retrieve document content (10–100KB each)

• Returns structured not_found when the ID doesn't exist

reliefweb_search_disasters

Search active and historical disasters on ReliefWeb.

• Filtering by disaster type (Earthquake, Flood, Cyclone, etc.), country, and status

• GLIDE number lookup for cross-system disaster correlation

• Date range filtering on disaster creation date

• Status values: alert, current, past, alert-archive, archive; multiple values comma-separated

• Optional include_archived=true for historical research

• Returns IDs for use with reliefweb_get_disaster and as disaster_id filter in reliefweb_search_reports

reliefweb_get_disaster

Fetch a disaster record by ReliefWeb numeric ID with full details.

• Full description, profile overview, affected countries, and GLIDE number

• Currently-active curated key content links from the ReliefWeb editorial team (the present set, not the full archive)

• Currently-active appeals and response plans linked to the disaster

• Currently-active useful external links curated by ReliefWeb editors

reliefweb_get_country

Fetch a country profile from ReliefWeb by ISO3 code.

• Situation overview text curated by OCHA editors

• Currently-active key content links maintained by ReliefWeb editors (the present curated set, not the full archive)

• Currently-active humanitarian appeals and response plans

• Currently-active useful external links for the country

• Country profiles are the authoritative situation summary for humanitarian responders

reliefweb_list_countries

List all countries and territories tracked by ReliefWeb.

• 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

reliefweb_search_jobs

Search humanitarian job listings on ReliefWeb.

• Filtering by country, organization short name, career category, theme, and experience level

• Career category values: Programme and Project Management, Information and Communications Technology, Logistics and Telecommunications, and others

• Returns current open positions — archived jobs excluded by default

• Sortable by newest posting (date.created:desc, default) or soonest closing (date.closing:asc)

• Pagination with closing date and canonical URL per listing

reliefweb_search_training

Search humanitarian training and learning opportunities.

• Covers on-site and online capacity-building events

• Filtering by country, source, format, career category, and language

• Date range filtering on training start date (date_start_from / date_start_to)

• Ordered by soonest start date by default (date.start:asc); override with sort

• Distinct from report date fields — uses date.start / date.end

reliefweb_list_sources

Browse organizations that contribute content to ReliefWeb.

• 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

• Use shortname with the source filter in reliefweb_search_reports, reliefweb_search_jobs, and reliefweb_search_training

Related MCP server: mcp-rss-feed-searcher

Resources and prompt

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation

• Unified error handling across all tools

• Pluggable auth (none, jwt, oauth)

• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1

• Structured logging with optional OpenTelemetry tracing

• Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

ReliefWeb-specific:

• Full coverage of six ReliefWeb content types: reports, disasters, countries, jobs, training, sources

• Compound filter builder supporting nested AND/OR conditions for the ReliefWeb API v2

• RELIEFWEB_APP_NAME validated at startup (required by the API since November 2025)

• 1,000 calls/day quota awareness — prominently documented on each tool

Agent-friendly output:

• Body text excluded from search results by design — agents fetch it explicitly with reliefweb_get_report to control context budget

• Recovery hints on empty results — echoes applied filters and suggests how to broaden

• Typed not_found error contracts on get-by-ID tools with actionable recovery text

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"
      }
    }
  }
}

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

Configuration

All configuration is validated at startup via Zod schemas. Key environment variables:

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

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

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.