.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/reliefweb-mcp-server</h1> <p><b>Search ReliefWeb humanitarian reports, disasters, jobs, training, and country profiles via MCP. STDIO or Streamable HTTP.</b> <div>9 Tools • 3 Resources • 1 Prompt</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

<div align="center">

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

</div>

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
• Curated key content links from the ReliefWeb editorial team
• Active appeals and response plans linked to the disaster
• 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
• Key content links maintained by ReliefWeb editors
• Active humanitarian appeals and response plans
• 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 alert or current)
• 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
• Pagination with closing date and canonical URL per listing

reliefweb_search_training

Search humanitarian training and learning opportunities.

• Covers workshops, e-learning, conferences, seminars, and other 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)
• 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, NGO, Academia)
• 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

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

1. Navigate into the directory:

cd reliefweb-mcp-server

1. 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.