Skip to content

IBM/chuk-mcp-stac

BranchesTags

Repository files navigation

Chuk MCP STAC

Satellite Imagery Discovery & Retrieval MCP Server - A comprehensive Model Context Protocol (MCP) server for searching STAC catalogs, downloading satellite bands, and creating composites.

This is a demonstration project provided as-is for learning and testing purposes.

Python 3.11+

Features

This MCP server provides access to satellite imagery through STAC (SpatioTemporal Asset Catalog) APIs via twenty-one tools.

All tools return fully-typed Pydantic v2 models for type safety, validation, and excellent IDE support. All tools support output_mode="text" for human-readable output alongside the default JSON.

1. Catalog Discovery (stac_list_catalogs)

List available STAC catalogs:

  • Earth Search (AWS) and Planetary Computer (Microsoft)
  • Shows default catalog and available endpoints

2. Collection Browsing (stac_list_collections)

Browse collections in a catalog:

  • List all available satellite collections
  • Spatial and temporal extents
  • Collection descriptions and metadata

3. Scene Search (stac_search)

Search for satellite scenes:

  • Bounding box spatial queries
  • Date range filtering
  • Cloud cover thresholds
  • Collection filtering (Sentinel-2, Landsat, etc.)
  • Configurable result limits

4. Scene Details (stac_describe_scene)

Get detailed metadata for a scene:

  • Available bands and assets
  • CRS and projection info
  • Cloud cover, datetime, spatial extent
  • Filters out metadata-only assets

5. Scene Preview (stac_preview)

Get a preview/thumbnail URL for a scene:

  • Returns rendered_preview or thumbnail asset URL
  • Prefers rendered previews over thumbnails
  • Fast visual browsing without downloading full bands

6. Band Download (stac_download_bands)

Download specific bands from a scene:

  • Any combination of bands (red, green, blue, nir, etc.)
  • Hardware band aliases supported (B04, B08, SR_B4, etc.)
  • Optional bbox cropping in EPSG:4326
  • Output as GeoTIFF or PNG (auto-stretched)
  • SCL-based cloud masking (Sentinel-2 only)

7. RGB Composite (stac_download_rgb)

Download true-color RGB composites:

  • Convenience wrapper for red, green, blue bands
  • Automatic band resolution matching
  • PNG output for inline LLM rendering

8. Custom Composite (stac_download_composite)

Create multi-band composites:

  • Any band combination (e.g., false-color infrared: nir, red, green)
  • Named composites for easy identification
  • Cloud masking and PNG output support

9. Spectral Index (stac_compute_index)

Compute spectral indices for a scene:

  • NDVI, NDWI, NDBI, EVI, SAVI, BSI
  • Automatically selects required bands
  • Cloud masking (masked pixels → NaN)
  • Output as float32 GeoTIFF or stretched PNG

10. Mosaic (stac_mosaic)

Merge multiple scenes into a single raster:

  • Combines overlapping scenes
  • Standard merge (last) or quality-weighted (best pixel via SCL)
  • Per-scene cloud masking before merge

11. Time Series (stac_time_series)

Extract temporal band data:

  • Searches scenes across a date range
  • Downloads bands for each date
  • Concurrent downloads for performance
  • Cloud cover filtering

12. Server Status (stac_status)

Check server configuration:

  • Server version and storage provider
  • Default catalog
  • Artifact store availability

13. Capabilities (stac_capabilities)

List full server capabilities for LLM workflow planning:

  • Available catalogs and collections
  • Spectral indices with required bands
  • Band mappings by satellite platform
  • Tool count

14. Size Estimation (stac_estimate_size)

Estimate download size before committing to a full download:

  • Reads only COG headers (no pixel data transferred)
  • Per-band dimensions, dtype, and byte estimates
  • Warnings for large downloads (>=500MB, >=1GB)

15. Collection Intelligence (stac_describe_collection)

Get detailed collection metadata with LLM-friendly guidance:

  • Band wavelengths and resolutions
  • Recommended composite recipes
  • Supported spectral indices
  • Cloud masking info and usage guidance

16. Conformance Checking (stac_get_conformance)

Check which STAC API features a catalog supports:

  • Parses conformance URIs into feature flags
  • Core, item_search, filter, sort, fields, query, collections

17. Find Scene Pairs (stac_find_pairs)

Find before/after scene pairs for change detection:

  • Separate before and after date ranges
  • Computes spatial overlap percentage per pair
  • Caches all found scenes for follow-up download

18. Coverage Check (stac_coverage_check)

Verify cached scenes fully cover a target area:

  • Rasterizes bounding box into a 100x100 grid
  • Returns coverage percentage and uncovered areas
  • Ensures full spatial coverage before download

19. Queryable Properties (stac_queryables)

Fetch queryable properties from a STAC API:

  • Catalog-level or collection-scoped queryables
  • Property names, types, descriptions, and enum values
  • Enables advanced CQL2 filter construction

20. Temporal Composite (stac_temporal_composite)

Combine multiple scenes via per-pixel statistics:

  • Methods: median, mean, max, min
  • Reduces cloud contamination in time series
  • SCL-based cloud masking per scene before compositing

21. Zonal Statistics (stac_zonal_stats)

Read a raster's values within zones — the inference step after a fetch:

  • Per-zone n_valid / mean / std / min / max / median / p10 / p90
  • Zones as points + buffer_m (circular) or GeoJSON polygons, in any CRS
  • Optional background_m annulus → a local z-score (anomaly readout) for cropmark / feature detection

Installation

Using uvx (Recommended - No Installation Required!)

uvx chuk-mcp-stac

Using uv (Recommended for Development)

# Install from PyPI
uv pip install chuk-mcp-stac

# Or clone and install from source
git clone <repository-url>
cd chuk-mcp-stac
uv sync --dev

Using pip (Traditional)

pip install chuk-mcp-stac

Usage

With Claude Desktop

Option 1: Run Locally with uvx

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "stac": {
      "command": "uvx",
      "args": ["chuk-mcp-stac"]
    }
  }
}

Option 2: Run Locally with pip

{
  "mcpServers": {
    "stac": {
      "command": "chuk-mcp-stac"
    }
  }
}

Standalone

Run the server directly:

# With uvx (recommended - always latest version)
uvx chuk-mcp-stac

# With uvx in HTTP mode
uvx chuk-mcp-stac http

# Or if installed locally
chuk-mcp-stac
chuk-mcp-stac http

Or with uv/Python:

# STDIO mode (default, for MCP clients)
uv run chuk-mcp-stac
# or: python -m chuk_mcp_stac.server

# HTTP mode (for web access)
uv run chuk-mcp-stac http
# or: python -m chuk_mcp_stac.server http

STDIO mode is for MCP clients like Claude Desktop and mcp-cli. HTTP mode runs a web server on http://localhost:8002 for HTTP-based MCP clients.

Example Usage

Once configured, you can ask Claude questions like:

  • "Search for Sentinel-2 imagery over London from last month"
  • "Download an RGB composite of that scene"
  • "Show me a false-color infrared view using NIR, red, and green bands"
  • "Compute the NDVI for this scene with cloud masking"
  • "Create a mosaic of these overlapping scenes"
  • "Get a time series of NDVI data for this farm over the growing season"
  • "What collections are available on Earth Search?"
  • "Describe the Sentinel-2 collection — what bands and composites are available?"
  • "How big would downloading 4 bands from that scene be?"
  • "What STAC API features does Earth Search support?"

Demo Scripts

The examples/ directory contains 19 runnable demos covering all 21 tools. Each script is self-contained and produces a PNG output in examples/output/.

Core Tool Demos

Script Network? Tools Demonstrated
capabilities_demo.py No stac_capabilities, stac_status, stac_list_catalogs
collection_intel_demo.py Yes stac_describe_collection, stac_get_conformance, stac_estimate_size
colchester_from_space.py Yes stac_search → stac_download_rgb → stac_compute_index
mosaic_demo.py Yes stac_search → stac_describe_scene → stac_mosaic
time_series_demo.py Yes stac_time_series → stac_download_bands
landsat_demo.py Yes stac_search → stac_download_bands (Landsat band aliases)
change_detection_demo.py Yes stac_find_pairs → stac_preview → stac_coverage_check
false_color_demo.py Yes stac_describe_collection → stac_download_composite
temporal_composite_demo.py Yes stac_list_collections → stac_queryables → stac_temporal_composite

Real-World Showcase Demos

Script Location What It Shows
wildfire_scar_demo.py California, USA Park Fire burn scar — before/after RGB, NDVI, false-colour SWIR composite
uk_flooding_demo.py Lincolnshire, UK Storm Babet flooding — NDWI water index before/after with cloud masking
coastal_erosion_demo.py Yorkshire, UK Holderness coast retreat — 2019 vs 2024 NDWI coastline comparison
crop_health_demo.py Cambridgeshire, UK Wheat phenology — cloud-masked NDVI across growing season
dubai_growth_demo.py Dubai, UAE Urban expansion — 2022 vs 2024 NDBI built-up index
vegas_f1_demo.py Las Vegas, USA F1 race infrastructure — summer vs race week NDBI comparison
amazon_deforestation_demo.py Rondônia, Brazil Dry season NDVI time series tracking deforestation
lake_chad_demo.py Chad/Nigeria Seasonal water extent — NDWI wet vs dry season
singapore_port_demo.py Singapore Port activity — RGB time series across 6 months
alps_snow_demo.py Mont Blanc, Alps Snow cover — custom NDSI winter vs summer 
cd examples
python capabilities_demo.py        # no network required
python colchester_from_space.py     # full search → download → render pipeline
python wildfire_scar_demo.py        # before/after burn scar comparison

Tool Reference

All tools accept an optional output_mode parameter ("json" default, or "text" for human-readable output). Download tools that produce GeoTIFF output automatically generate a PNG preview (preview_ref in the response).

stac_search

{
  "bbox": [0.85, 51.85, 0.95, 51.92],        # [west, south, east, north]
  "collection": "sentinel-2-c1-l2a",           # optional
  "date_range": "2024-06-01/2024-08-31",       # optional
  "max_cloud_cover": 20,                        # 0-100, optional
  "max_items": 10,                              # optional
  "catalog": "earth_search"                     # optional
}

stac_download_bands

{
  "scene_id": "S2B_...",                        # from search results
  "bands": ["red", "green", "blue", "nir"],     # common names or aliases (B04, SR_B4)
  "bbox": [0.85, 51.85, 0.95, 51.92],          # optional crop
  "output_format": "geotiff",                   # "geotiff" or "png"
  "cloud_mask": false                            # Sentinel-2 only
}

stac_download_rgb

{
  "scene_id": "S2B_...",
  "bbox": [0.85, 51.85, 0.95, 51.92],          # optional crop
  "output_format": "png",                        # "geotiff" or "png"
  "cloud_mask": false                            # Sentinel-2 only
}

stac_download_composite

{
  "scene_id": "S2B_...",
  "bands": ["nir", "red", "green"],             # false-color infrared
  "composite_name": "false_color_ir",           # optional label
  "bbox": [0.85, 51.85, 0.95, 51.92],          # optional crop
  "output_format": "geotiff",                   # "geotiff" or "png"
  "cloud_mask": false                            # Sentinel-2 only
}

stac_compute_index

{
  "scene_id": "S2B_...",
  "index_name": "ndvi",                         # ndvi, ndwi, ndbi, evi, savi, bsi
  "bbox": [0.85, 51.85, 0.95, 51.92],          # optional crop
  "cloud_mask": true,                            # mask clouds with NaN
  "output_format": "geotiff"                    # "geotiff" or "png"
}

stac_mosaic

{
  "scene_ids": ["S2B_001", "S2B_002"],
  "bands": ["red", "green", "blue"],
  "bbox": [0.85, 51.85, 0.95, 51.92],          # optional
  "method": "last",                              # "last" or "quality" (SCL-based)
  "output_format": "geotiff",                   # "geotiff" or "png"
  "cloud_mask": false                            # per-scene masking before merge
}

stac_time_series

{
  "bbox": [0.85, 51.85, 0.95, 51.92],
  "bands": ["red", "nir"],
  "date_range": "2024-01-01/2024-12-31",
  "collection": "sentinel-2-c1-l2a",            # optional
  "max_cloud_cover": 10,                         # optional
  "max_items": 50,                               # optional
  "catalog": "earth_search"                      # optional
}

stac_estimate_size

{
  "scene_id": "S2B_...",
  "bands": ["red", "green", "blue", "nir"],
  "bbox": [0.85, 51.85, 0.95, 51.92]            # optional crop
}

stac_describe_collection

{
  "collection_id": "sentinel-2-l2a",
  "catalog": "earth_search",                     # optional
  "output_mode": "text"                          # optional: "json" or "text"
}

stac_get_conformance

{
  "catalog": "earth_search",                     # optional
  "output_mode": "json"                          # optional: "json" or "text"
}

Development

Setup

# Clone the repository
git clone <repository-url>
cd chuk-mcp-stac

# Install with uv (recommended)
uv sync --dev

# Or with pip
pip install -e ".[dev]"

Running Tests

make test              # Run tests
make test-cov          # Run tests with coverage
make coverage-report   # Show coverage report

Code Quality

make lint      # Run linters
make format    # Auto-format code
make typecheck # Run type checking
make security  # Run security checks
make check     # Run all checks

Building

make build         # Build package
make docker-build  # Build Docker image

Deployment

Fly.io

Deploy to Fly.io with a single command:

# First time setup
fly launch

# Deploy updates
fly deploy

Docker

# Build the image
docker build -t chuk-mcp-stac .

# Run the container
docker run -p 8002:8002 chuk-mcp-stac

Architecture

Built on top of chuk-mcp-server, this server uses:

  • Async-First: Native async/await with sync rasterio wrapped in asyncio.to_thread()
  • Type-Safe: Pydantic v2 models with extra="forbid" for all responses
  • Efficient I/O: Cloud-Optimized GeoTIFF (COG) reading with windowed access
  • Smart Caching: LRU scene cache (200 entries), TTL client cache (300s), in-memory raster cache (100 MB LRU)
  • Band Resolution Matching: Automatic bilinear resampling when bands differ in resolution
  • Band Aliases: Hardware names (B04, SR_B4) resolved to common names at entry
  • Artifact Storage: Pluggable storage via chuk-artifacts (memory, filesystem, S3)
  • CRS Handling: Automatic EPSG:4326 to native CRS reprojection for bbox queries
  • Cloud Masking: SCL-based masking for Sentinel-2 (integer → 0, float → NaN)
  • Spectral Indices: NDVI, NDWI, NDBI, EVI, SAVI, BSI with automatic band selection
  • PNG Output: 2nd-98th percentile stretch for visual inspection and LLM rendering
  • Auto-Preview: PNG preview auto-generated alongside every GeoTIFF download (preview_ref)
  • Temporal Compositing: Pixel-by-pixel statistical composites (median, mean, max, min)
  • Quality Mosaics: SCL-based best-pixel selection for quality-weighted merges
  • Progress Callbacks: Optional progress reporting for long-running operations
  • PC Auth: Automatic Planetary Computer asset signing when package is installed
  • Dual Output: All 21 tools support output_mode="text" for human-readable responses

See ARCHITECTURE.md for design principles and data flow diagrams. See SPEC.md for the full tool specification with parameter tables. See ROADMAP.md for development status and planned features.

Supported Catalogs

Catalog Collections URL
Earth Search (AWS) Sentinel-2, Landsat, NAIP, MODIS earth-search.aws.element84.com
Planetary Computer (Microsoft) Sentinel-2, Landsat, MODIS planetarycomputer.microsoft.com
USGS Landsat Look Landsat landsatlook.usgs.gov

Also supports Sentinel-1 SAR (VV/VH) and Copernicus DEM GLO-30 collections.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

Apache License 2.0 - See LICENSE for details.

Acknowledgments

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages