kuzhang/mcp-gee-satellite-download

GEE MCP Server

Python MCP server exposing a tool to download Google Earth Engine imagery as GeoTIFF.

Prerequisites

• Google Earth Engine account approved
• Python 3.10+
• Local Earth Engine auth completed for the user account

Credentials

Server (GEE)

The server supports two auth methods. Use ONE of these:

1. Service account key file (recommended)

• Place gee-key.json in the project root (same folder as server.py).
• The file should be a standard Google service account JSON with fields like type, project_id, private_key_id, private_key, client_email, client_id, etc.
• Optionally set GEE_PROJECT in .env (or it will use project_id from the key file).

2. Environment variables

• Set the following in your environment (or .env if your launcher loads it):

GEE_PROJECT=your-gcp-project-id
GEE_SERVICE_ACCOUNT=service-account@your-project.iam.gserviceaccount.com
GEE_PRIVATE_KEY_PATH=C:\path\to\service-account.json
# Alternative to GEE_PRIVATE_KEY_PATH:
GOOGLE_APPLICATION_CREDENTIALS=C:\path\to\service-account.json

Notes:

• The server automatically detects gee-key.json if present; otherwise it tries env vars, then default user auth.
• Run earthengine authenticate once if you prefer user auth locally.

Client (LLM)

The client uses an LLM for prompt parsing. Create a .env in the project root with:

OPENAI_API_KEY=sk-...
# Optional, defaults to gpt-4o-mini
OPENAI_MODEL=gpt-4o-mini

Passing env to the server

When the client spawns the server (stdio), it forwards the most relevant GEE env vars if set:

• GEE_PROJECT
• GEE_SERVICE_ACCOUNT
• GEE_PRIVATE_KEY_PATH
• GOOGLE_APPLICATION_CREDENTIALS

If you rely on gee-key.json, no additional env configuration is required.

Setup

python -m venv .venv
. .venv/Scripts/activate  # on Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -r requirements.txt

Authenticate Earth Engine (one-time):

earthengine authenticate

If running on a headless server, set service account credentials via env GOOGLE_APPLICATION_CREDENTIALS or use ee.ServiceAccountCredentials in code.

Run Server (MCP over stdio)

python server.py

The server exposes one tool:

• download_satellite_image(DownloadParams) -> str: Downloads a GeoTIFF to a temp file and returns its absolute path.

DownloadParams

• latitude (float)
• longitude (float)
• start_date (YYYY-MM-DD)
• end_date (YYYY-MM-DD)
• scale (int, meters, default 10)
• buffer_m (int, default 1000)
• bands (str, comma-separated; default B4,B3,B2)
• dataset (str, default COPERNICUS/S2)

Run Client (CLI)

The CLI connects to the server over stdio, prompts for parameters, and calls the tool:

python client.py

MCP Client Config Example (Cursor / Claude Desktop)

Add a server entry similar to:

{
  "mcpServers": {
    "gee-mcp": {
      "command": "python",
      "args": ["server.py"],
      "env": {}
    }
  }
}

Notes

• Ensure your date window and location intersect the dataset footprint.
• For Sentinel-2, the tool prefers the least cloudy image automatically.
• Large regions or small scales may produce big downloads; adjust buffer_m and scale accordingly.
• Don't give too large region to download at once, the split function in server may fails.

Server functions and capabilities

Tools exposed

• download_satellite_image(DownloadParams) -> { files: string[], message: string }
  • Downloads one or more GeoTIFFs from Google Earth Engine for a user-defined Area of Interest (AOI).

Inputs (DownloadParams)

• Geographic input (provide exactly one):
  • latitude, longitude (float): point center; uses buffer_m to create AOI
  • bounding_box (number[4]): [min_lon, min_lat, max_lon, max_lat] (preferred for rectangles)
  • region_geojson (string): full GeoJSON for complex polygons
• Temporal and data options:
  • start_date, end_date (YYYY-MM-DD)
  • dataset (string): default COPERNICUS/S2_SR_HARMONIZED
  • bands (string): comma-separated band names (default B4,B3,B2)
  • scale (int, meters): target resolution
  • buffer_m (int): only used with point input
  • max_cloud_cover (float, %): filter cap for Sentinel-2
  • image_count (int): number of least-cloudy images to download

Processing behavior

• Sorts by cloud cover (Sentinel-2) and selects up to image_count images.
• Saves files to download/ with capture date in filename.
• Preflight size check and automatic tiling:
  • Estimates pixel count/bytes and splits AOI into quadrants when needed.
  • If a tile still exceeds GEE size limits, recursively splits further (limited depth) and/or increases scale (coarsens resolution) until the request fits.
• Robust region handling:
  • Converts bounding_box to a rectangular polygon.
  • Uses AOI bounds as the download region.
• Logging: detailed execution written to server.log (authentication, preflight, tiling, retries).

Outputs

• Returns { files: [absolute_file_paths], message: string }.
  • May return multiple files when AOI is split or multiple dates are requested.
  • Message indicates if fewer images were available than requested, or if tiling/scale backoff occurred.

Limits and notes

• Very large AOIs and/or small scale produce large requests; server will split tiles and increase scale automatically to satisfy GEE limits (~48 MB per request for thumbnails/downloads).
• Cloud-cover filtering currently applies to Sentinel‑2 collections (field CLOUDY_PIXEL_PERCENTAGE).
• If you need strict masking to the polygon footprint, consider adding an explicit clip(AOI) step before download.