mcp/hdx repository overview

⁠Humanitarian Data Exchange MCP Server

HDX MCP Server provides access to humanitarian data through the Humanitarian Data Exchange (HDX) API - https://data.humdata.org/hapi⁠. This server offers 33 specialized tools for retrieving humanitarian information including affected populations (refugees, IDPs, returnees), baseline demographics, food security indicators, conflict data, funding information, and operational presence across hundreds of countries and territories. See repository for instructions on getting a free HDX_APP_INDENTIFIER for access.

What is an MCP Server?⁠

⁠MCP Info

⁠Image Building Info

Attribute	Details
Dockerfile	https://github.com/dividor/hdx-mcp/blob/c625bf9ae120ed93a36aa7ac9352bdc41f6d9546/Dockerfile⁠
Commit	c625bf9ae120ed93a36aa7ac9352bdc41f6d9546
Docker Image built by	Docker Inc.
Docker Scout Health Score
Verify Signature	COSIGN_REPOSITORY=mcp/signatures cosign verify mcp/hdx --key https://raw.githubusercontent.com/docker/keyring/refs/heads/main/public/mcp/latest.pub
Licence	MIT License

⁠Available Tools (29)

⁠Tools Details

⁠Tool: affected_people_humanitarian_needs_get

OCHA's Humanitarian Needs data, based on the Joint and Intersectoral Analysis Framework (JIAF), provides information about the number of people in need during a crisis. See the more detailed technical HDX HAPI documentation⁠, and the original JIAF source⁠ website.

Query Parameters:

• app_identifier (Required): base64 encoded application name and email, as in base64("app_name:email"). This value can also be passed in the X-HDX-HAPI-APP-IDENTIFIER header. See the encoded_app_identifier endpoint.

• category: A category combining gender, age range, disability marker and population group information

• sector_code: Filter the response by the sector code.

• population_status: Filter the response by the population status, available values are described here.⁠

• population_min: Filter the response by a lower bound for the population.

• population_max: Filter the response by a upper bound for the population.

• sector_name: Filter the response by the sector name.

• has_hrp: Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.

• in_gho: Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the Global Humanitarian Overview⁠.

• start_date: Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00

• end_date: Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59

• location_code: Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. Use the metadata_location_get tool to get available location codes and names.

• location_name: Filter the response by a location (typically a country). The location names are based on the "short name" from the UN M49 Standard⁠. Use the metadata_location_get tool to get available location codes and names.

• admin1_code: Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the Common Operational Datasets⁠. Use the metadata_admin1_get tool to get available admin1 codes and names.

• admin1_name: Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the Common Operational Datasets⁠ or those provided in the original data source. Use the metadata_admin1_get tool to get available admin1 codes and names.

• admin2_code: Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the Common Operational Datasets⁠. Use the metadata_admin2_get tool to get available admin2 codes and names.

• admin2_name: Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the Common Operational Datasets⁠ or those provided in the original data source. Use the metadata_admin2_get tool to get available admin2 codes and names.

• admin_level: Filter the response by admin level.

• output_format: No description.

• limit: Maximum number of records to return. The system will not return more than 10,000 records.

• offset: Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.

Responses:

• 200 (Success): Successful Response

  • Content-Type: application/json

  • Response Properties:

  • Example:

{
  "data": [
    {
      "location_code": "string",
      "location_name": "string",
      "admin1_code": "unknown_type",
      "admin_level": 1,
      "reference_period_end": "unknown_type",
      "population_status": "AFF",
      "admin2_name": "unknown_type",
      "admin1_name": "unknown_type",
      "resource_hdx_id": "string",
      "sector_code": "string",
      "population": 1,
      "reference_period_start": "2024-01-01T12:00:00Z",
      "sector_name": "unknown_type",
      "category": "string",
      "admin2_code": "unknown_type"
    }
  ]
}

• 400: Bad Request

  • Content-Type: application/json

  • Response Properties:

  • Example:

{
  "detail": "string"
}

• 422: Validation Error

  • Content-Type: application/json

  • Response Properties:

  • Example:

{
  "detail": [
    {
      "loc": [
        "unknown_type"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

• 500: Internal Server Error

  • Content-Type: application/json

  • Response Properties:

  • Example:

{
  "error_sample_list": [
    "unknown"
  ],
  "error": "string"
}

⁠Tool: affected_people_idps_get

Get idps data

🎯 CRITICAL - Data Coverage Warning: Data coverage is only determined by the metadata_data_availability_get tool. Just because a country is in the system doesn't mean it has data. ALWAYS verify data availability before making data queries.

🎯 CRITICAL - Administrative Level Efficiency: Before making aggregate queries (totals, country-wide statistics), ALWAYS check data availability using metadata_data_availability_get for the target country. Use the LOWEST available admin level (0=country, 1=state, 2=district) to avoid downloading excessive granular data. For country totals, use admin level 0 if available, otherwise level 1. Never query admin level 2 for simple aggregations when level 0/1 is sufficient.

🔄 Pagination: You can page through results using limit and offset parameters (limit=records per page, offset=starting position).

⚠️ CRITICAL - Never Manually Aggregate Data: IMPORTANT: Never sum data yourself, only take the data verbatim from the tool. NEVER aggregate totals yourself to answer a question if you do not have the values already aggregated from the tool. Do NOT sum up individual records, calculate country-wide statistics from subnational data, or aggregate across time periods/demographics yourself. If data is not pre-aggregated, inform the user that aggregate data is not available. Always use the most appropriate administrative level that has pre-aggregated data.

Query Parameters:

• app_identifier (Required): base64 encoded application name and email, as in base64("app_name:email"). This value can also be passed in the X-HDX-HAPI-APP-IDENTIFIER header. See the encoded_app_identifier endpoint.

• has_hrp: Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.

• in_gho: Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the Global Humanitarian Overview⁠.

• start_date: Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00

• end_date: Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59

• location_code: Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. Use the metadata_location_get tool to get available location codes and names.

• location_name: Filter the response by a location (typically a country). The location names are based on the "short name" from the UN M49 Standard⁠. Use the metadata_location_get tool to get available location codes and names.

• admin1_code: Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the Common Operational Datasets⁠. Use the metadata_admin1_get tool to get available admin1 codes and names.

• admin1_name: Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the Common Operational Datasets⁠ or those provided in the original data source. Use the metadata_admin1_get tool to get available admin1 codes and names.

• admin2_code: Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the Common Operational Datasets⁠. Use the metadata_admin2_get tool to get available admin2 codes and names.

• admin2_name: Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the Common Operational Datasets⁠ or those provided in the original data source. Use the metadata_admin2_get tool to get available admin2 codes and names.

• admin_level: Filter the response by admin level.

• output_format: No description.

• limit: Maximum number of records to return. The system will not return more than 10,000 records.

• offset: Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.

Responses:

• 200 (Success): Successful Response

  • Content-Type: application/json

  • Response Properties:

  • Example:

{
  "data": [
    {
      "location_code": "string",
      "location_name": "string",
      "admin1_code": "unknown_type",
      "admin_level": 1,
      "reference_period_end": "unknown_type",
      "assessment_type": "BA",
      "admin2_name": "unknown_type",
      "admin1_name": "unknown_type",
      "resource_hdx_id": "string",
      "population": 1,
      "operation": "string",
      "reference_period_start": "2024-01-01T12:00:00Z",
      "reporting_round": 1,
      "admin2_code": "unknown_type"
    }
  ]
}

• 400: Bad Request

  • Content-Type: application/json

  • Response Properties:

  • Example:

{
  "detail": "string"
}

• 422: Validation Error

  • Content-Type: application/json

  • Response Properties:

  • Example:

{
  "detail": [
    {
      "loc": [
        "unknown_type"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

• 500: Internal Server Error

  • Content-Type: application/json

  • Response Properties:

  • Example:

{
  "error_sample_list": [
    "unknown"
  ],
  "error": "string"
}

⁠Tool: affected_people_refugees_get

UNHCR's Refugee data provides information about displaced people in a crisis. See the more detailed technical HDX HAPI documentation⁠, and the original HDX source⁠ website.

Query Parameters:

• app_identifier (Required): base64 encoded application name and email, as in base64("app_name:email"). This value can also be passed in the X-HDX-HAPI-APP-IDENTIFIER header. See the encoded_app_identifier endpoint.

• population_group: Filter the response by the population group, available values are described here.⁠

• population_min: Filter the response by a lower bound for the population.

• population_max: Filter the response by a upper bound for the population.

• gender: Filter the response by the gender, available values are described here.⁠

• age_range: Filter the response by the age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data.

• origin_location_code: Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. Use the metadata_location_get tool to get available location codes and names.

• origin_location_name: F

[...]