io.github.cyanheads/reliefweb-mcp-server

Official11 toolsLive

by cyanheads · TypeScript

Search ReliefWeb humanitarian reports, disasters, jobs, training, and country profiles via MCP.

@cyanheads/reliefweb-mcp-server

io.github.cyanheads/reliefweb-mcp-server is an MCP server that searches ReliefWeb content, covering humanitarian reports, disasters, jobs, training, and country profiles. It exposes 11 tools and can run over STDIO or Streamable HTTP, with details provided in the repository documentation.

🛠️ Key Features

MCP server for ReliefWeb search
11 tools
Topics include crisis-data, disasters, humanitarian-aid, and OCHA-related data
Runs via STDIO or Streamable HTTP

🚀 Use Cases

Locate humanitarian reports and disaster information
Find jobs and training listings
Retrieve country profiles from ReliefWeb

⚡ Developer Benefits

Uses Model Context Protocol for tool access (mcp, mcp-server, model-context-protocol)
Repository indicates implementation in TypeScript (typescript, bun)
Clear resource counts shown in README excerpt: 3 resources and 1 prompt

⚠️ Limitations

Server scope is limited to ReliefWeb categories listed in the description (reports, disasters, jobs, training, country profiles)

Topics

ai-agentbuncrisis-datadisastershumanitarianhumanitarian-aidmcpmcp-servermodel-context-protocolochareliefwebtypescriptcyanheads

Captured live from the server via tools/list.

reliefweb_search_reports

Search humanitarian reports on ReliefWeb with filtering by country, disaster, format, theme, language, source, and date. Returns paginated summaries — use reliefweb_get_report to fetch full body text. Report body is excluded from results (10–100KB each); call get_report when document content is needed. Every report is reachable by default — reports have no archived class, so include_archived has no effect here. Note: each call counts against the 1,000 calls/day quota.

Parameters14

text	string	optional	Full-text search query. Matches against title, body, and key metadata fields. Use plain natural language or keywords.
country	string	optional	ISO 3166-1 alpha-3 country code (e.g., SYR, AFG, UKR). Filters to content tagged with this country.
disaster_id	integer	optional	ReliefWeb numeric disaster ID. Filters to reports linked to a specific disaster. Get the ID from reliefweb_search_disasters.
format	string	optional	Content format filter. One of: News and Press Release, Situation Report, Map, Infographic, Analysis, Other, Assessment, Manual and Guideline, Appeal, UN Document, Evaluation and Lessons Learned. Case, spacing, and punctuation are ignored; any other value is rejected with the valid list.
theme	string	optional	Sector or cross-cutting theme (e.g., Health, Food and Nutrition, Shelter and Non-Food Items, Protection). Open-ended — matches theme.name exactly as ReliefWeb spells it.
language	string	optional	ISO 639-1 language code (e.g., en, fr, es, ar). Filters on language.code.
source	string	optional	Organization short name (e.g., UNHCR, OCHA, WFP). Filters on source.shortname.
date_from	any	optional	Earliest publication date. Filters on date.original (source publication date). A bare calendar date such as 2024-01-15 is accepted and resolves to start of that day in UTC; a datetime carrying any offset is resolved to UTC.
date_to	any	optional	Latest publication date. Pair with date_from for a date range. A bare calendar date resolves to end of that day in UTC, so the range covers it in full; a datetime carrying any offset is resolved to UTC.
sort	string	optional	Sort order. Use date.original:desc for newest first (default), date.original:asc for oldest first, score:desc for relevance.
include_archived	boolean	optional	No effect on reports. Reports have no archived class — every report is already in scope, whatever this is set to. Kept so existing calls that pass it keep working; it is meaningful on reliefweb_search_jobs, reliefweb_search_training, and reliefweb_search_disasters.
filter	object	optional	Raw ReliefWeb filter object for compound conditions not covered by named params. Example: {"operator": "AND", "conditions": [{"field": "format.name", "value": "Map"}, {"field": "language.code", "value": "fr"}]}.
limit	integer	optional	Number of results to return (1–1000, default 10). Use a smaller value for targeted lookups; larger for bulk research. Each call counts against the 1,000-calls/day quota.
offset	integer	optional	Zero-based offset for pagination. Use with limit and the totalCount enrichment field to page through large result sets.

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "description": "Full-text search query. Matches against title, body, and key metadata fields. Use plain natural language or keywords.",
      "type": "string"
    },
    "country": {
      "description": "ISO 3166-1 alpha-3 country code (e.g., SYR, AFG, UKR). Filters to content tagged with this country.",
      "type": "string"
    },
    "disaster_id": {
      "description": "ReliefWeb numeric disaster ID. Filters to reports linked to a specific disaster. Get the ID from reliefweb_search_disasters.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "format": {
      "description": "Content format filter. One of: News and Press Release, Situation Report, Map, Infographic, Analysis, Other, Assessment, Manual and Guideline, Appeal, UN Document, Evaluation and Lessons Learned. Case, spacing, and punctuation are ignored; any other value is rejected with the valid list.",
      "type": "string"
    },
    "theme": {
      "description": "Sector or cross-cutting theme (e.g., Health, Food and Nutrition, Shelter and Non-Food Items, Protection). Open-ended — matches theme.name exactly as ReliefWeb spells it.",
      "type": "string"
    },
    "language": {
      "description": "ISO 639-1 language code (e.g., en, fr, es, ar). Filters on language.code.",
      "type": "string"
    },
    "source": {
      "description": "Organization short name (e.g., UNHCR, OCHA, WFP). Filters on source.shortname.",
      "type": "string"
    },
    "date_from": {
      "description": "Earliest publication date. Filters on date.original (source publication date). A bare calendar date such as 2024-01-15 is accepted and resolves to start of that day in UTC; a datetime carrying any offset is resolved to UTC.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})?)?$",
          "description": "Calendar date (2024-01-15) or full ISO 8601 datetime (2024-01-15T00:00:00+00:00)."
        }
      ]
    },
    "date_to": {
      "description": "Latest publication date. Pair with date_from for a date range. A bare calendar date resolves to end of that day in UTC, so the range covers it in full; a datetime carrying any offset is resolved to UTC.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})?)?$",
          "description": "Calendar date (2024-01-31) or full ISO 8601 datetime (2024-01-31T23:59:59+00:00)."
        }
      ]
    },
    "sort": {
      "description": "Sort order. Use date.original:desc for newest first (default), date.original:asc for oldest first, score:desc for relevance.",
      "type": "string"
    },
    "include_archived": {
      "description": "No effect on reports. Reports have no archived class — every report is already in scope, whatever this is set to. Kept so existing calls that pass it keep working; it is meaningful on reliefweb_search_jobs, reliefweb_search_training, and reliefweb_search_disasters.",
      "type": "boolean"
    },
    "filter": {
      "description": "Raw ReliefWeb filter object for compound conditions not covered by named params. Example: {\"operator\": \"AND\", \"conditions\": [{\"field\": \"format.name\", \"value\": \"Map\"}, {\"field\": \"language.code\", \"value\": \"fr\"}]}.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "limit": {
      "default": 10,
      "description": "Number of results to return (1–1000, default 10). Use a smaller value for targeted lookups; larger for bulk research. Each call counts against the 1,000-calls/day quota.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "offset": {
      "default": 0,
      "description": "Zero-based offset for pagination. Use with limit and the totalCount enrichment field to page through large result sets.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

reliefweb_get_report

Fetch a single ReliefWeb report by its numeric ID with full body text, file attachments, and all metadata. Use after reliefweb_search_reports to retrieve document content — body is excluded from search results to manage context budget. Report bodies can be 10–100KB. A record over the response budget comes back as a section outline naming every section and its byte size; re-call with sections to pull only the ones needed. Nothing is truncated on either path.

Parameters2

id	integer	required	ReliefWeb numeric report ID. Obtained from reliefweb_search_reports results.
sections	array	optional	Sections of the report record to return, named by the sections[].name values an outline response lists. Omit for the whole record, or for a section outline when the record is over the response budget. Identity metadata — the record's ID, its name, and its canonical URL — comes back alongside whatever is requested. The call is self-contained — the record is re-fetched and sliced, so no prior call has to be repeated.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "ReliefWeb numeric report ID. Obtained from reliefweb_search_reports results."
    },
    "sections": {
      "description": "Sections of the report record to return, named by the sections[].name values an outline response lists. Omit for the whole record, or for a section outline when the record is over the response budget. Identity metadata — the record's ID, its name, and its canonical URL — comes back alongside whatever is requested. The call is self-contained — the record is re-fetched and sliced, so no prior call has to be repeated.",
      "type": "array",
      "items": {
        "type": "string",
        "description": "A section name exactly as the outline response spelled it."
      }
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

reliefweb_search_disasters

Search active and historical disasters on ReliefWeb by type, country, status, date range, and GLIDE number. Default preset covers alert, ongoing, and past disasters. Use include_archived=true to reach alert-archive entries as well, for historical research. Returns IDs suitable for use with reliefweb_get_disaster and as disaster_id filter in reliefweb_search_reports.

Parameters11

text	string	optional	Full-text search query. Matches against disaster name and description.
country	string	optional	ISO 3166-1 alpha-3 country code (e.g., SYR, AFG, UKR). Filters to disasters tagged with this country.
disaster_type	string	optional	Disaster type name (e.g., Earthquake, Flood, Drought, Cyclone). Filters on type.name.
status	string	optional	Disaster status filter. One of: alert (newly declared), ongoing, past (resolved), alert-archive. Separate multiple values with commas; case, spacing, and punctuation are ignored, and any other value is rejected with the valid list. alert-archive is only reachable with include_archived=true — asking for it without that returns nothing.
glide	string	optional	GLIDE number (global disaster identifier, e.g., EQ-2023-000053-TUR). Use for cross-system disaster correlation.
date_from	any	optional	Earliest disaster creation date. Filters on date.created. A bare calendar date such as 2024-01-15 is accepted and resolves to start of that day in UTC; a datetime carrying any offset is resolved to UTC.
date_to	any	optional	Latest disaster creation date. Pair with date_from for a date range. A bare calendar date resolves to end of that day in UTC, so the range covers it in full; a datetime carrying any offset is resolved to UTC.
sort	string	optional	Sort order. Use date.created:desc for newest first (default), date.created:asc for oldest, score:desc for relevance.
include_archived	boolean	optional	Include alert-archive disasters in results, alongside alert, ongoing, and past. Uses preset=analysis. Off by default.
limit	integer	optional	Number of results to return (1–1000, default 10). Each call counts against the 1,000-calls/day quota.
offset	integer	optional	Zero-based offset for pagination. Use with limit and the totalCount enrichment field to page through results.

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "description": "Full-text search query. Matches against disaster name and description.",
      "type": "string"
    },
    "country": {
      "description": "ISO 3166-1 alpha-3 country code (e.g., SYR, AFG, UKR). Filters to disasters tagged with this country.",
      "type": "string"
    },
    "disaster_type": {
      "description": "Disaster type name (e.g., Earthquake, Flood, Drought, Cyclone). Filters on type.name.",
      "type": "string"
    },
    "status": {
      "description": "Disaster status filter. One of: alert (newly declared), ongoing, past (resolved), alert-archive. Separate multiple values with commas; case, spacing, and punctuation are ignored, and any other value is rejected with the valid list. alert-archive is only reachable with include_archived=true — asking for it without that returns nothing.",
      "type": "string"
    },
    "glide": {
      "description": "GLIDE number (global disaster identifier, e.g., EQ-2023-000053-TUR). Use for cross-system disaster correlation.",
      "type": "string"
    },
    "date_from": {
      "description": "Earliest disaster creation date. Filters on date.created. A bare calendar date such as 2024-01-15 is accepted and resolves to start of that day in UTC; a datetime carrying any offset is resolved to UTC.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})?)?$",
          "description": "Calendar date (2024-01-15) or full ISO 8601 datetime (2024-01-15T00:00:00+00:00)."
        }
      ]
    },
    "date_to": {
      "description": "Latest disaster creation date. Pair with date_from for a date range. A bare calendar date resolves to end of that day in UTC, so the range covers it in full; a datetime carrying any offset is resolved to UTC.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})?)?$",
          "description": "Calendar date (2024-01-31) or full ISO 8601 datetime (2024-01-31T23:59:59+00:00)."
        }
      ]
    },
    "sort": {
      "description": "Sort order. Use date.created:desc for newest first (default), date.created:asc for oldest, score:desc for relevance.",
      "type": "string"
    },
    "include_archived": {
      "description": "Include alert-archive disasters in results, alongside alert, ongoing, and past. Uses preset=analysis. Off by default.",
      "type": "boolean"
    },
    "limit": {
      "default": 10,
      "description": "Number of results to return (1–1000, default 10). Each call counts against the 1,000-calls/day quota.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "offset": {
      "default": 0,
      "description": "Zero-based offset for pagination. Use with limit and the totalCount enrichment field to page through results.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

reliefweb_get_disaster

Fetch a disaster record by ReliefWeb numeric ID including description, affected countries, GLIDE number, profile overview, key content links, and active appeals or response plans. Use after reliefweb_search_disasters to retrieve full details. Each curated list also has an archive, which the record leaves out. Two alternative selectors, at most one per call: sections names parts of the record to return, archive pages one list's archived entries in place of the record. Description and profile overview can together run to tens of KB for major disasters. A record over the response budget comes back as a section outline naming every section and its byte size. Nothing is truncated on any path.

Parameters3

id	integer	required	ReliefWeb numeric disaster ID. Obtained from reliefweb_search_disasters results.
sections	array	optional	Sections of the disaster record to return, named by the sections[].name values an outline response lists. Omit for the whole record, or for a section outline when the record is over the response budget. Identity metadata — the record's ID, its name, and its canonical URL — comes back alongside whatever is requested. The call is self-contained — the record is re-fetched and sliced, so no prior call has to be repeated. This names parts of the record itself and never reaches archived entries — use archive for those.
archive	object	optional	Archive mode: return a page of one curated list's ARCHIVED entries instead of the disaster record. The response carries the record identity, the selected list, and total / shown / offset, plus a next offset while more entries remain. Mutually exclusive with sections — sections slices the record, archive replaces it — and a call supplying both is rejected. A record over the response budget still answers an archive call with the page: a page is bounded by limit and carries none of the record prose, so it never outlines.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "ReliefWeb numeric disaster ID. Obtained from reliefweb_search_disasters results."
    },
    "sections": {
      "description": "Sections of the disaster record to return, named by the sections[].name values an outline response lists. Omit for the whole record, or for a section outline when the record is over the response budget. Identity metadata — the record's ID, its name, and its canonical URL — comes back alongside whatever is requested. The call is self-contained — the record is re-fetched and sliced, so no prior call has to be repeated. This names parts of the record itself and never reaches archived entries — use archive for those.",
      "type": "array",
      "items": {
        "type": "string",
        "description": "A section name exactly as the outline response spelled it."
      }
    },
    "archive": {
      "description": "Archive mode: return a page of one curated list's ARCHIVED entries instead of the disaster record. The response carries the record identity, the selected list, and total / shown / offset, plus a next offset while more entries remain. Mutually exclusive with sections — sections slices the record, archive replaces it — and a call supplying both is rejected. A record over the response budget still answers an archive call with the page: a page is bounded by limit and carries none of the record prose, so it never outlines.",
      "type": "object",
      "properties": {
        "list": {
          "type": "string",
          "enum": [
            "keyContent",
            "appealsResponsePlans",
            "usefulLinks"
          ],
          "description": "Which curated list to page. The archived entries of that list are the ones the profile itself leaves out."
        },
        "offset": {
          "default": 0,
          "description": "Zero-based index of the first archived entry to return. Send back the nextOffset from the previous page to continue.",
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "limit": {
          "default": 25,
          "description": "Maximum archived entries in one page (1-100).",
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        }
      },
      "required": [
        "list"
      ]
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

reliefweb_get_country

Fetch a country profile from ReliefWeb by ISO3 code, including overview, humanitarian situation summary, key content links, active appeals and response plans, and useful external links. Country profiles are curated by OCHA editors and provide the authoritative situation summary for humanitarian responders. Each curated list also has an archive — thousands of entries deep for a long-running crisis — which the profile leaves out. Two alternative selectors, at most one per call: sections names parts of the profile to return, archive pages one list's archived entries in place of the profile. A profile over the response budget comes back as a section outline naming every section and its byte size. Nothing is truncated on any path.

Parameters3

iso3	string	required	ISO 3166-1 alpha-3 country code (e.g., SYR, AFG, UKR). Used to look up the country's ReliefWeb profile.
sections	array	optional	Sections of the country record to return, named by the sections[].name values an outline response lists. Omit for the whole record, or for a section outline when the record is over the response budget. Identity metadata — the record's ID, its name, and its canonical URL — comes back alongside whatever is requested. The call is self-contained — the record is re-fetched and sliced, so no prior call has to be repeated. This names parts of the profile itself and never reaches archived entries — use archive for those.
archive	object	optional	Archive mode: return a page of one curated list's ARCHIVED entries instead of the country record. The response carries the record identity, the selected list, and total / shown / offset, plus a next offset while more entries remain. Mutually exclusive with sections — sections slices the record, archive replaces it — and a call supplying both is rejected. A record over the response budget still answers an archive call with the page: a page is bounded by limit and carries none of the record prose, so it never outlines.

Raw schema

{
  "type": "object",
  "properties": {
    "iso3": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3,
      "description": "ISO 3166-1 alpha-3 country code (e.g., SYR, AFG, UKR). Used to look up the country's ReliefWeb profile."
    },
    "sections": {
      "description": "Sections of the country record to return, named by the sections[].name values an outline response lists. Omit for the whole record, or for a section outline when the record is over the response budget. Identity metadata — the record's ID, its name, and its canonical URL — comes back alongside whatever is requested. The call is self-contained — the record is re-fetched and sliced, so no prior call has to be repeated. This names parts of the profile itself and never reaches archived entries — use archive for those.",
      "type": "array",
      "items": {
        "type": "string",
        "description": "A section name exactly as the outline response spelled it."
      }
    },
    "archive": {
      "description": "Archive mode: return a page of one curated list's ARCHIVED entries instead of the country record. The response carries the record identity, the selected list, and total / shown / offset, plus a next offset while more entries remain. Mutually exclusive with sections — sections slices the record, archive replaces it — and a call supplying both is rejected. A record over the response budget still answers an archive call with the page: a page is bounded by limit and carries none of the record prose, so it never outlines.",
      "type": "object",
      "properties": {
        "list": {
          "type": "string",
          "enum": [
            "keyContent",
            "appealsResponsePlans",
            "usefulLinks"
          ],
          "description": "Which curated list to page. The archived entries of that list are the ones the profile itself leaves out."
        },
        "offset": {
          "default": 0,
          "description": "Zero-based index of the first archived entry to return. Send back the nextOffset from the previous page to continue.",
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "limit": {
          "default": 25,
          "description": "Maximum archived entries in one page (1-100).",
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        }
      },
      "required": [
        "list"
      ]
    }
  },
  "required": [
    "iso3"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

reliefweb_list_countries

List all countries and territories tracked by ReliefWeb, optionally filtered to active humanitarian situations. Returns ISO3 codes and status for each entry — use the ISO3 code with reliefweb_get_country to fetch a full profile. Set crisis_only=true to limit results to countries with active humanitarian situations.

Parameters3

crisis_only	boolean	optional	When true, filters to countries with an active humanitarian situation (status ongoing). Default false returns all countries.
limit	integer	optional	Number of results to return (1–1000, default 100). Each call counts against the 1,000-calls/day quota.
offset	integer	optional	Zero-based offset for pagination. Use with limit and the totalCount enrichment field to page through results.

Raw schema

{
  "type": "object",
  "properties": {
    "crisis_only": {
      "description": "When true, filters to countries with an active humanitarian situation (status ongoing). Default false returns all countries.",
      "type": "boolean"
    },
    "limit": {
      "default": 100,
      "description": "Number of results to return (1–1000, default 100). Each call counts against the 1,000-calls/day quota.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "offset": {
      "default": 0,
      "description": "Zero-based offset for pagination. Use with limit and the totalCount enrichment field to page through results.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

reliefweb_search_jobs

Search humanitarian job listings on ReliefWeb by country, organization, career category, theme, and experience level. Returns current open positions — expired postings are excluded by default. Use include_archived=true to search the full history of postings, which is far larger than the open set. Use text search for role titles and job descriptions.

Parameters10

text	string	optional	Full-text search query. Matches against job title, body, and key metadata fields.
country	string	optional	ISO 3166-1 alpha-3 country code (e.g., SYR, AFG, UKR). Filters to jobs tagged with this country.
source	string	optional	Organization short name (e.g., UNHCR, OCHA, WFP). Filters on source.shortname.
career_category	string	optional	Humanitarian career track (e.g., Programme and Project Management, Information and Communications Technology, Logistics and Telecommunications). Filters on career_categories.name.
theme	string	optional	Sector or cross-cutting theme (e.g., Health, Food and Nutrition, Protection). Filters on theme.name.
experience	string	optional	Experience level (e.g., 0-2 years, 3-4 years, 5-9 years). Filters on experience.name.
sort	string	optional	Sort order. Use date.created:desc for newest postings first (default), date.closing:asc to surface roles closing soonest, or score:desc for relevance.
include_archived	boolean	optional	Search expired postings alongside the open ones. Uses preset=analysis. Off by default — the open set is a small fraction of the archive, so turn this on for labour-market history rather than for a hiring snapshot.
limit	integer	optional	Number of results to return (1–1000, default 10). Each call counts against the 1,000-calls/day quota.
offset	integer	optional	Zero-based offset for pagination. Use with limit and the totalCount enrichment field to page through results.

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "description": "Full-text search query. Matches against job title, body, and key metadata fields.",
      "type": "string"
    },
    "country": {
      "description": "ISO 3166-1 alpha-3 country code (e.g., SYR, AFG, UKR). Filters to jobs tagged with this country.",
      "type": "string"
    },
    "source": {
      "description": "Organization short name (e.g., UNHCR, OCHA, WFP). Filters on source.shortname.",
      "type": "string"
    },
    "career_category": {
      "description": "Humanitarian career track (e.g., Programme and Project Management, Information and Communications Technology, Logistics and Telecommunications). Filters on career_categories.name.",
      "type": "string"
    },
    "theme": {
      "description": "Sector or cross-cutting theme (e.g., Health, Food and Nutrition, Protection). Filters on theme.name.",
      "type": "string"
    },
    "experience": {
      "description": "Experience level (e.g., 0-2 years, 3-4 years, 5-9 years). Filters on experience.name.",
      "type": "string"
    },
    "sort": {
      "description": "Sort order. Use date.created:desc for newest postings first (default), date.closing:asc to surface roles closing soonest, or score:desc for relevance.",
      "type": "string"
    },
    "include_archived": {
      "description": "Search expired postings alongside the open ones. Uses preset=analysis. Off by default — the open set is a small fraction of the archive, so turn this on for labour-market history rather than for a hiring snapshot.",
      "type": "boolean"
    },
    "limit": {
      "default": 10,
      "description": "Number of results to return (1–1000, default 10). Each call counts against the 1,000-calls/day quota.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "offset": {
      "default": 0,
      "description": "Zero-based offset for pagination. Use with limit and the totalCount enrichment field to page through results.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

reliefweb_get_job

Fetch a job posting by ReliefWeb numeric ID with the full vacancy description, application instructions, dates, hiring organization, and location and taxonomy metadata. Use after reliefweb_search_jobs, which returns summaries without the description or application instructions. Reaches expired postings as well as open ones. A record over the response budget comes back as a section outline naming every section and its byte size; re-call with sections to pull only the ones needed. Nothing is truncated on either path.

Parameters2

id	integer	required	ReliefWeb numeric job ID. Obtained from reliefweb_search_jobs results.
sections	array	optional	Sections of the job record to return, named by the sections[].name values an outline response lists. Omit for the whole record, or for a section outline when the record is over the response budget. Identity metadata — the record's ID, its name, and its canonical URL — comes back alongside whatever is requested. The call is self-contained — the record is re-fetched and sliced, so no prior call has to be repeated.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "ReliefWeb numeric job ID. Obtained from reliefweb_search_jobs results."
    },
    "sections": {
      "description": "Sections of the job record to return, named by the sections[].name values an outline response lists. Omit for the whole record, or for a section outline when the record is over the response budget. Identity metadata — the record's ID, its name, and its canonical URL — comes back alongside whatever is requested. The call is self-contained — the record is re-fetched and sliced, so no prior call has to be repeated.",
      "type": "array",
      "items": {
        "type": "string",
        "description": "A section name exactly as the outline response spelled it."
      }
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

reliefweb_search_training

Search humanitarian training and learning opportunities on ReliefWeb by country, format, date, source, career category, and language. Covers on-site and online capacity-building events. Training date fields use date.start / date.end — different from report date fields. Use date_start_from and date_start_to to find upcoming training within a window. Results default to soonest-starting first (date.start:asc). With neither date bound supplied the search is scoped to training starting from now, so the first page is upcoming opportunities; supply either bound to search an explicit range, including a historical one. Use include_archived=true to search concluded listings as well, which are far more numerous than the current ones.

Parameters12

text	string	optional	Full-text search query. Matches against training title and description.
country	string	optional	ISO 3166-1 alpha-3 country code (e.g., KEN, ETH, COD). Filters to training tagged with this country.
source	string	optional	Organization short name. Filters on source.shortname.
format	string	optional	Training format. Valid values: on-site, online. Filters on format.name.
career_category	string	optional	Humanitarian career track (e.g., Programme and Project Management, Information and Communications Technology). Filters on career_categories.name.
language	string	optional	ISO 639-1 language code (e.g., en, fr, es). Filters on language.code.
date_start_from	any	optional	Training start date lower bound. Filters on date.start — use to find training starting after a given date. A bare calendar date resolves to start of that day in UTC, and a datetime carrying any offset is resolved to UTC. Omit this and date_start_to together to default the search to training starting from now, unless include_archived is set, which leaves the range open.
date_start_to	any	optional	Training start date upper bound. Filters on date.start — pair with date_start_from for a window. A bare calendar date resolves to end of that day in UTC, and a datetime carrying any offset is resolved to UTC. Supplying this alone searches everything up to it, with no lower bound injected.
sort	string	optional	Sort order. Use date.start:asc for soonest-starting training first (default), date.start:desc for latest-starting, date.created:desc for most recently posted, or score:desc for relevance.
include_archived	boolean	optional	Search concluded listings alongside the current ones. Uses preset=analysis. Off by default. Setting this also drops the start-from-now default bound, so an otherwise unbounded search reaches back through the whole record; pair it with date_start_from and date_start_to to study a specific period.
limit	integer	optional	Number of results to return (1–1000, default 10). Each call counts against the 1,000-calls/day quota.
offset	integer	optional	Zero-based offset for pagination. Use with limit and the totalCount enrichment field to page through results.

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "description": "Full-text search query. Matches against training title and description.",
      "type": "string"
    },
    "country": {
      "description": "ISO 3166-1 alpha-3 country code (e.g., KEN, ETH, COD). Filters to training tagged with this country.",
      "type": "string"
    },
    "source": {
      "description": "Organization short name. Filters on source.shortname.",
      "type": "string"
    },
    "format": {
      "description": "Training format. Valid values: on-site, online. Filters on format.name.",
      "type": "string",
      "enum": [
        "on-site",
        "online"
      ]
    },
    "career_category": {
      "description": "Humanitarian career track (e.g., Programme and Project Management, Information and Communications Technology). Filters on career_categories.name.",
      "type": "string"
    },
    "language": {
      "description": "ISO 639-1 language code (e.g., en, fr, es). Filters on language.code.",
      "type": "string"
    },
    "date_start_from": {
      "description": "Training start date lower bound. Filters on date.start — use to find training starting after a given date. A bare calendar date resolves to start of that day in UTC, and a datetime carrying any offset is resolved to UTC. Omit this and date_start_to together to default the search to training starting from now, unless include_archived is set, which leaves the range open.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})?)?$",
          "description": "Calendar date (2024-06-01) or full ISO 8601 datetime (2024-06-01T00:00:00+00:00)."
        }
      ]
    },
    "date_start_to": {
      "description": "Training start date upper bound. Filters on date.start — pair with date_start_from for a window. A bare calendar date resolves to end of that day in UTC, and a datetime carrying any offset is resolved to UTC. Supplying this alone searches everything up to it, with no lower bound injected.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})?)?$",
          "description": "Calendar date (2024-12-31) or full ISO 8601 datetime (2024-12-31T23:59:59+00:00)."
        }
      ]
    },
    "sort": {
      "description": "Sort order. Use date.start:asc for soonest-starting training first (default), date.start:desc for latest-starting, date.created:desc for most recently posted, or score:desc for relevance.",
      "type": "string"
    },
    "include_archived": {
      "description": "Search concluded listings alongside the current ones. Uses preset=analysis. Off by default. Setting this also drops the start-from-now default bound, so an otherwise unbounded search reaches back through the whole record; pair it with date_start_from and date_start_to to study a specific period.",
      "type": "boolean"
    },
    "limit": {
      "default": 10,
      "description": "Number of results to return (1–1000, default 10). Each call counts against the 1,000-calls/day quota.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "offset": {
      "default": 0,
      "description": "Zero-based offset for pagination. Use with limit and the totalCount enrichment field to page through results.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

reliefweb_get_training

Fetch a training listing by ReliefWeb numeric ID with the full description, registration instructions, event link, cost and fee information, dates, languages, and organizing source. Use after reliefweb_search_training, which returns summaries without the description, registration instructions, or cost detail. Reaches concluded listings as well as current ones. A record over the response budget comes back as a section outline naming every section and its byte size; re-call with sections to pull only the ones needed. Nothing is truncated on either path.

Parameters2

id	integer	required	ReliefWeb numeric training ID. Obtained from reliefweb_search_training results.
sections	array	optional	Sections of the training record to return, named by the sections[].name values an outline response lists. Omit for the whole record, or for a section outline when the record is over the response budget. Identity metadata — the record's ID, its name, and its canonical URL — comes back alongside whatever is requested. The call is self-contained — the record is re-fetched and sliced, so no prior call has to be repeated.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "ReliefWeb numeric training ID. Obtained from reliefweb_search_training results."
    },
    "sections": {
      "description": "Sections of the training record to return, named by the sections[].name values an outline response lists. Omit for the whole record, or for a section outline when the record is over the response budget. Identity metadata — the record's ID, its name, and its canonical URL — comes back alongside whatever is requested. The call is self-contained — the record is re-fetched and sliced, so no prior call has to be repeated.",
      "type": "array",
      "items": {
        "type": "string",
        "description": "A section name exactly as the outline response spelled it."
      }
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

reliefweb_list_sources

Browse source organizations that contribute content to ReliefWeb, optionally filtered by name text or organization type. Returns short names, types, and URLs. Use the shortname value with the source filter in reliefweb_search_reports, reliefweb_search_jobs, and reliefweb_search_training.

Parameters4

text	string	optional	Full-text search query. Matches against organization name and short name.
type	string	optional	Organization type. One of: Non-governmental Organization, International Organization, Academic and Research Institution, Other, Government, Media, Red Cross/Red Crescent Movement. Filters on type.name.
limit	integer	optional	Number of results to return (1–1000, default 10). Each call counts against the 1,000-calls/day quota.
offset	integer	optional	Zero-based offset for pagination. Use with limit and the totalCount enrichment field to page through results.

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "description": "Full-text search query. Matches against organization name and short name.",
      "type": "string"
    },
    "type": {
      "description": "Organization type. One of: Non-governmental Organization, International Organization, Academic and Research Institution, Other, Government, Media, Red Cross/Red Crescent Movement. Filters on type.name.",
      "type": "string",
      "enum": [
        "Non-governmental Organization",
        "International Organization",
        "Academic and Research Institution",
        "Other",
        "Government",
        "Media",
        "Red Cross/Red Crescent Movement"
      ]
    },
    "limit": {
      "default": 10,
      "description": "Number of results to return (1–1000, default 10). Each call counts against the 1,000-calls/day quota.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "offset": {
      "default": 0,
      "description": "Zero-based offset for pagination. Use with limit and the totalCount enrichment field to page through results.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md19 KBView on GitHub

@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

MCP SDK TypeScript

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

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:

json

{
  "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.

json

{
  "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):

json

{
  "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:

json

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

Clone the repository:

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

Navigate into the directory:

cd reliefweb-mcp-server

Install dependencies:

bun install

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.

Install

Tools (11)

reliefweb_search_reportsreliefweb_get_reportreliefweb_search_disastersreliefweb_get_disasterreliefweb_get_countryreliefweb_list_countriesreliefweb_search_jobsreliefweb_get_job

Configuration

Environment variables

RELIEFWEB_APP_NAMErequired

Pre-approved appname for the ReliefWeb API v2. Required since November 2025.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_TRANSPORT_TYPEdefault http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_PUBLIC_URL

Public origin override for deployments behind a TLS-terminating reverse proxy.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "reliefweb-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/reliefweb-mcp-server@0.2.3"
      ],
      "env": {
        "RELIEFWEB_APP_NAME": "<YOUR_RELIEFWEB_APP_NAME>",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

@cyanheads/reliefweb-mcp-server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

reliefweb_search_reports

reliefweb_get_report

reliefweb_search_disasters

reliefweb_get_disaster

reliefweb_get_country

reliefweb_list_countries

reliefweb_search_jobs

reliefweb_get_job

reliefweb_search_training

reliefweb_get_training

reliefweb_list_sources

@cyanheads/reliefweb-mcp-server

Overview

Tools

Resources

Prompts

Capability reference

reliefweb_search_reports tool

reliefweb_get_report tool

reliefweb_search_disasters tool

reliefweb_get_disaster tool

reliefweb_get_country tool

reliefweb_list_countries tool

reliefweb_search_jobs tool

reliefweb_get_job tool

reliefweb_search_training tool

reliefweb_get_training tool

reliefweb_list_sources tool

reliefweb://reports/{id} resource

reliefweb://disasters/{id} resource

reliefweb://countries/{iso3} resource

reliefweb_crisis_briefing prompt

Features

Getting started

Prerequisites

Public Hosted Instance

Self-Hosted / Local

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`reliefweb_search_reports` _tool

`reliefweb_get_report` _tool

`reliefweb_search_disasters` _tool

`reliefweb_get_disaster` _tool

`reliefweb_get_country` _tool

`reliefweb_list_countries` _tool

`reliefweb_search_jobs` _tool

`reliefweb_get_job` _tool

`reliefweb_search_training` _tool

`reliefweb_get_training` _tool

`reliefweb_list_sources` _tool

`reliefweb://reports/{id}` _resource

`reliefweb://disasters/{id}` _resource

`reliefweb://countries/{iso3}` _resource

`reliefweb_crisis_briefing` _prompt