UNHCR Open Data Gateway MCP

A FastMCP-based gateway that aggregates and normalizes data from UNHCR's domain-specific MCP servers.

🎯 Purpose

The UNHCR Open Data Gateway MCP provides a unified interface for accessing UNHCR's open data across three independent MCP servers:

• Statistics MCP: Authoritative source for population and displacement data

• RDF MCP: Authoritative source for socio-economic indicators and contextual datasets

• IATI MCP: Authoritative source for budget, contributions, and financial transparency data

Related MCP server: dataset-search-mcp

🏗️ Architecture

The gateway follows a Federated Gateway Pattern:

                    AI Client
                         |
                         v

            +----------------------+
            |  Open Data Gateway   |
            |       FastMCP        |
            +----------------------+

                 /      |      \

                /       |       \

               v        v        v

        +---------+ +---------+ +---------+
        | Stat    | | RDF     | | IATI    |
        | MCP     | | MCP     | | MCP     |
        +---------+ +---------+ +---------+

                   ^
                   |
                   |
          Reference Layer
          (Canonical Entities)

Core Principles

1. Domain MCP Ownership: Each domain MCP owns its data

2. Gateway Owns Experience: Gateway handles aggregation, composition, discovery, analytics

3. Domain MCP Independence: Domain MCPs never call each other directly

4. Canonical Reference Layer: Prevents duplication of country/operation definitions

🚀 Quick Start

Installation

# Clone the repository
git clone <repository-url>
cd unhcr-opendata-gateway-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Configuration

Create a .env file:

STAT_MCP_ENDPOINT=http://localhost:8001
RDF_MCP_ENDPOINT=http://localhost:8002
IATI_MCP_ENDPOINT=http://localhost:8003
LOG_LEVEL=INFO

Running the Server

# Run in STDIO mode
python -m src.unhcr_opendata_gateway.app

🛠️ Usage

Available Tools

Example Queries

# Get a country snapshot
result = await country_snapshot(country="Uganda", year=2023)

# Calculate funding gap
result = await funding_gap_analysis(country="Chad", year=2023)

# Compare two countries
result = await compare_countries(country_a="Uganda", country_b="Kenya", year=2023)

# Generate a briefing note
result = await generate_country_brief(country="Sudan", year=2023)

📊 Features

• Country Normalization: Handles ISO3, ISO2, names, aliases, "Republic of X" variants

• Cross-Domain Analytics: Funding gap per refugee, budget per refugee, etc.

• Graceful Degradation: Returns partial data when some MCPs are unavailable

• Caching: TTL-based caching with configurable expiration

• Observability: Structured logging, metrics, OpenTelemetry tracing

📄 License

Apache License 2.0

🙏 Support

For issues or questions, please contact the UNHCR Data team.