hdx

HDX MCP Server exposes a suite of tools that grant AI assistants access to the Humanitarian Data Exchange API. It includes metadata discovery tools (to fetch locations, datasets, organizations, sectors, and more), affected people data (refugees, humanitarian needs, IDPs, and returns), demographics and geography, climate data, coordination and context data, food security and poverty statistics, utilities, and custom HDX tools for server information and dataset lookup. You can connect to the server from clients like Claude Desktop or MCP Inspectors by using the MCP transport endpoint and the appropriate server configuration. The server is designed to be run locally or remotely (via Docker or UV) and to respond to a variety of tool calls that query the HDX API and return structured results suitable for conversational QA or agent workflows.

Prerequisites:

• Docker installed (recommended) or UV for Python setup.
• Access to the internet to reach the HDX API.
• An HDX application identifier (HDX_APP_IDENTIFIER) obtained from the HDX API page.

Option A: Install and run via Docker (recommended)

1. Ensure Docker Desktop is installed and running.
2. Prepare a .env file with required variables (see Configuration section) and save as ./hdx-mcp/.env.
3. Build or pull the HDX MCP server image (the README references the image name hdx-mcp-server).
4. Run the server via Docker: docker run --rm -i --env-file ./hdx-mcp/.env hdx-mcp-server
5. The MCP server will expose the endpoint for clients to connect (e.g., http transport if configured).

Option B: Run via UV (Python) (advanced)

1. Install UV: curl -LsSf https://astral.sh/uv/install.sh | sh
2. Clone the repository and install dependencies: git clone https://github.com/dividor/hdx-mcp.git cd hdx-mcp uv sync --all-extras --dev
3. Copy and customize env.example to .env and fill in HDX_APP_IDENTIFIER and related vars.
4. Start the server: uv run hdx-mcp-server --transport http --host 0.0.0.0 --port 8000 --verbose

Prerequisites recap:

• Access to Docker or UV depending on your chosen deployment method.
• A valid HDX APP identifier (HDX_APP_IDENTIFIER).
• Optional: customize HDX_BASE_URL and other HDX_ environment variables as needed.

Tips and common issues:

• Ensure HDX_BASE_URL is reachable from the host where the MCP server runs. If running behind a firewall or proxy, configure network access accordingly.
• If you encounter authentication or quota limits with the HDX API, consider applying for higher limits or scheduling queries to avoid rate limiting.
• When using Claude Desktop or other MCP clients, ensure the MCP transport (e.g., HTTP) matches what the server exposes and that the path /mcp is reachable.
• Use the provided example environment file as a starting point and keep non-sensitive defaults in code while keeping secrets in your .env file not checked into version control.
• If you upgrade the HDX MCP server image or code, re-check the environment variables names and defaults as they may change between versions.