The UNICEF Google Earth Engine (GEE) MCP Server provides access to geospatial data and analysis capabilities through Google Earth Engine. This Model Context Protocol (MCP) server exposes specialized tools for querying, processing, and visualizing geospatial datasets related to children's environmental risks and demographics.

This MCP server serves as the geospatial data backend for the UNICEF Geosphere project, providing access to:

• Hazard Datasets: Natural disaster and climate risk data (floods, droughts, heatwaves, storms)
• Demographic Data: Population and children-specific spatial datasets
• Spatial Analysis: Advanced geospatial processing and visualization tools

• Dataset Discovery: Browse available hazard and demographic datasets
• Image Processing: Filter, mask, threshold, and combine geospatial images
• Feature Operations: Spatial intersections, unions, and merging
• Spatial Analysis: Zonal statistics and area calculations
• Map Generation: Interactive HTML map creation with visualizations

• Multi-hazard Analysis: Combine different hazard datasets
• Population Exposure: Calculate children at risk from environmental hazards
• Custom Visualizations: Generate maps with UNICEF-specific styling

• Google Earth Engine: Planetary-scale geospatial analysis, official GEE client library
• FastMCP: Model Context Protocol server framework
• Folium: Interactive map generation

ee_mcp/
├── server.py              # MCP server and tool definitions
├── handlers.py            # Tool implementation and business logic
├── config.py              # Configuration and settings management
├── initialize.py          # Google Earth Engine authentication setup
├── datasets.py            # Dataset catalog and metadata
├── utils.py               # Utility functions for data processing
├── schemas.py             # Pydantic models and validation
├── constants.py           # Application constants
├── hazards_metadata.yaml  # Comprehensive dataset metadata
├── config.yaml            # Server configuration
└── logging_config.py      # Logging setup

Before setting up the UNICEF GEE MCP Server, ensure you have:

• An active Google Cloud Project with Earth Engine API enabled
• A dedicated service account with JSON key file for server authentication
• Earth Engine access permissions granted to the service account
• Permissions to access UNICEF's private Earth Engine assets

# Install dependencies using uv
uv sync

1. Create service account in Google Cloud Console
2. Download JSON key file
3. Enable Earth Engine API for your project
4. Grant Earth Engine access to the service account

The server requires Google Earth Engine authentication via service account:

# Set service account credentials
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

# Or mount as Docker secret
/run/secrets/ee_auth.json

ee_mcp/config.yaml:

server:
  host: "0.0.0.0" # Server bind address
  port: 6002 # Internal MCP port
  transport: "sse" # MCP transport protocol

The server is reachable only on the internal Docker network. The agent connects via geospatial_mcp:6002/sse.

The server uses hazards_metadata.yaml for dataset definitions. See the full guide: Adding a new dataset.

Each dataset entry must include the following fields:

Required Fields:

• image_filename (string): Conventional JSON filename used by workflows that cache images.
• asset_id (string, suffix only): Earth Engine asset id suffix (prefixed at load time with projects/unicef-ccri/assets).
• description (string): Human-readable description of the dataset.
• source_name (string): Data source organization name.
• source_url (string): URL to the original data source or documentation.

Optional Fields:

• mosaic (boolean, default: false): Whether to mosaic an ImageCollection.
• threshold (number | "mean"): Default threshold; "mean" computes the global land mean at load time.
• color_palette (array): Hex color codes for visualization, from low to high values.
• input_arguments (object): Free-form settings for higher-level workflows.

For an example entry and validation tips, see docs/adding-dataset.md.

The MCP server exposes 12 specialized tools for geospatial analysis:

Returns comprehensive information about all available datasets.

Returns: Dictionary with dataset IDs, descriptions, sources, and visualization parameters.

Retrieves a specific dataset image with its metadata.

Parameters:

• dataset_id: Identifier for the dataset (e.g., "river_flood", "agricultural_drought")

Returns: Earth Engine Image object with metadata.

Applies a spatial mask to an image using a geometry.

Parameters:

• image_data: Serialized Earth Engine Image
• geometry_data: Serialized Earth Engine Geometry for masking

Returns: Masked image with only values within the geometry.

Filters image pixels based on value thresholds.

Parameters:

• image_data: Serialized Earth Engine Image
• threshold: Numeric threshold value
• comparison: Comparison operator ("gt", "gte", "lt", "lte", "eq")

Returns: Binary image with pixels meeting the threshold condition.

Creates a union (OR operation) of two binary images.

Returns: Combined image showing areas where either input image has values.

Creates an intersection (AND operation) of two binary images.

Returns: Combined image showing areas where both input images have values.

Finds spatial intersection between two feature collections.

Parameters:

• fc1_data: Serialized Earth Engine FeatureCollection
• fc2_data: Serialized Earth Engine FeatureCollection

Returns: Features that spatially intersect between the two collections.

Combines two feature collections into one.

Returns: Merged FeatureCollection containing all features from both inputs.

Performs spatial reduction (statistics) over an image within a geometry.

Parameters:

• image_data: Serialized Earth Engine Image
• geometry_data: Serialized Earth Engine Geometry
• reducer: Reduction operation ("sum", "mean", "count", "max", "min")

Returns: Statistical result of the reduction operation.

Creates a buffer zone around a geometry.

Parameters:

• geometry_data: Serialized Earth Engine Geometry
• buffer_distance: Buffer distance in meters

Returns: Buffered geometry representing the zone of area.

Generates an interactive HTML map visualization.

Parameters:

• image_data: Serialized Earth Engine Image
• geometry_data: Serialized Earth Engine Geometry
• vis_params: Visualization parameters (colors, opacity, etc.)

Returns: HTML string containing interactive map with data layers.

# Development mode
mcp dev ee_mcp/server.py

# Production mode
uv run ee_mcp/server.py

# Run all tests
uv run pytest

# Run integration tests
uv run pytest tests/test_integration.py -v

These helper scripts generate data used by tests and quick analyses. They require Google Earth Engine access and a service account key (ee_auth.json in the project root or the path configured in ee_mcp/config.yaml).

• scripts/baseline.py

  • Calculates baseline children exposure at ADM0 (country) for a set of hazards.
  • Saves per-hazard CSV outputs to ./output/.
  • Run:

    uv run python scripts/baseline.py

• scripts/multi_hazards.py

  • Computes multi-hazard exposure (both/either and per-hazard) using handlers and metadata in ee_mcp/hazards_metadata.yaml.
  • Writes intermediate EE objects to data/123/ and logs summary stats.
  • Run:

    uv run python scripts/multi_hazards.py

1. Clone repository
2. Install dependencies: uv sync
3. Set up GEE authentication
4. Configure test environment
5. Run tests to verify setup

• Service Account Keys: Securely managed via Docker secrets
• Least Privilege: Service account has minimal required permissions
• Private Assets: UNICEF datasets stored in private Earth Engine assets
• Network Security: Server accessible only within internal network

Required secret for runtime:

• ee_auth.json: Google service account key (mounted as Docker secret). The path is configured in ee_mcp/config.yaml (path_to_ee_auth).

Notes:

• The service account must have Earth Engine access and permissions to the required assets.

1. Code Style: Follow PEP 8 and use type hints
2. Testing: Add comprehensive tests for new tools
3. Documentation: Update tool descriptions and examples

1. Define tool in server.py with @mcp.tool() decorator
2. Implement handler in handlers.py
3. Add validation schemas in schemas.py
4. Write tests in tests/test_handlers.py
5. Update documentation in README

1. Add metadata to hazards_metadata.yaml
2. Verify asset permissions for Earth Engine assets
3. Test data access with integration tests
4. Document data sources and licensing

This project is licensed under the MIT License. See the LICENSE file for details.

• Issues: Submit issues on GitHub repository
• Earth Engine Support: Google Earth Engine Help Center
• UNICEF Data: Contact UNICEF data team for asset access
• Technical Support: Repository maintainers