Ryan Malloy
110b85c829
Five new prompts guide LLMs through multi-tool workflows: satellite_snapshot, climate_monitor, layer_deep_dive, multi_layer_story, polar_watch. README documents all 11 tools, 5 resources, and 7 prompts with example conversations. MIT license, project URLs, and updated classifiers for PyPI.
275 lines
11 KiB
Markdown
275 lines
11 KiB
Markdown
# mcgibs
|
|
|
|
NASA Earth science visualizations for LLMs.
|
|
|
|
An [MCP](https://modelcontextprotocol.io/) server that connects language models to [NASA GIBS](https://www.earthdata.nasa.gov/engage/open-data-services-software/earthdata-developer-portal/gibs-api) (Global Imagery Browse Services) — 1000+ visualization layers covering satellite imagery, scientific data products, and derived Earth observations, updated daily.
|
|
|
|
**Three pillars:**
|
|
|
|
- **Discovery** — search layers by keyword, browse measurement categories, check date availability
|
|
- **Visualization** — fetch imagery and data products by place name and date, compare dates side-by-side, composite multiple layers
|
|
- **Interpretation** — natural-language colormap explanations, legend graphics, scientific context
|
|
|
|
No API key required. All data is freely available from NASA.
|
|
|
|
## Quick Start
|
|
|
|
### From PyPI
|
|
|
|
```bash
|
|
uvx mcgibs
|
|
```
|
|
|
|
### Add to Claude Code
|
|
|
|
```bash
|
|
claude mcp add mcgibs -- uvx mcgibs
|
|
```
|
|
|
|
### Local development
|
|
|
|
```bash
|
|
git clone https://git.supported.systems/rpm/mcgibs.git
|
|
cd mcgibs
|
|
uv sync --all-extras
|
|
uv run mcgibs
|
|
```
|
|
|
|
Or add a local dev server to Claude Code:
|
|
|
|
```bash
|
|
claude mcp add mcgibs-local -- uv run --directory /path/to/mcgibs mcgibs
|
|
```
|
|
|
|
## Tools
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `search_gibs_layers` | Search 1000+ layers by keyword, measurement, period, or status |
|
|
| `get_layer_info` | Full metadata for a layer — instrument, platform, resolution, dates |
|
|
| `list_measurements` | All measurement categories with layer counts |
|
|
| `check_layer_dates` | Available date range for a layer (capabilities + live DescribeDomains) |
|
|
| `get_imagery` | Fetch a visualization by layer, date, and place name or bbox |
|
|
| `compare_dates` | Side-by-side comparison of two dates for change detection |
|
|
| `get_imagery_composite` | Overlay up to 5 layers into a single composite image |
|
|
| `explain_layer_colormap` | Natural-language explanation of what colors represent |
|
|
| `get_legend` | Pre-rendered legend graphic for a layer |
|
|
| `resolve_place` | Geocode a place name to coordinates and bounding box |
|
|
| `build_tile_url` | Construct a direct WMTS tile URL for embedding |
|
|
|
|
## Resources
|
|
|
|
| URI | Description |
|
|
|-----|-------------|
|
|
| `gibs://catalog` | Full layer catalog grouped by measurement category |
|
|
| `gibs://layer/{layer_id}` | Individual layer metadata as JSON |
|
|
| `gibs://colormap/{layer_id}` | Colormap explanation for a layer |
|
|
| `gibs://dates/{layer_id}` | Available date range for a layer |
|
|
| `gibs://projections` | Supported GIBS projections and endpoints |
|
|
|
|
## Prompts
|
|
|
|
| Prompt | Parameters | Description |
|
|
|--------|------------|-------------|
|
|
| `earth_overview` | *(none)* | Introduction to GIBS with suggested explorations |
|
|
| `investigate_event` | `event_type`, `location`, `date` | Guided workflow for investigating natural events |
|
|
| `satellite_snapshot` | `place`, `date` | Quick satellite view of any location |
|
|
| `climate_monitor` | `indicator`, `location`, `start_date`, `end_date` | Track climate changes over time |
|
|
| `layer_deep_dive` | `layer_id`, `location`, `date` | Full scientific analysis of a single layer |
|
|
| `multi_layer_story` | `topic`, `location`, `date` | Data journalism — composite layers to tell a story |
|
|
| `polar_watch` | `pole`, `date`, `compare_date` | Arctic/Antarctic ice and snow monitoring |
|
|
|
|
## Conversational Examples
|
|
|
|
These examples show what interacting with mcgibs looks like from any MCP client. Tool calls and responses are abbreviated for readability.
|
|
|
|
### "What's happening in the Amazon right now?"
|
|
|
|
*Try this with the `satellite_snapshot` prompt: `place="Amazon Rainforest"`*
|
|
|
|
> **You:** Show me what the Amazon rainforest looks like from space today.
|
|
|
|
The assistant resolves the location, fetches true color imagery, and searches for relevant science layers:
|
|
|
|
```
|
|
→ resolve_place("Amazon Rainforest")
|
|
{"display_name": "Amazon Rainforest", "lat": -3.46, "lon": -62.21,
|
|
"bbox": {"west": -73.98, "south": -16.52, "east": -43.75, "north": 5.27}}
|
|
|
|
→ get_imagery("MODIS_Terra_CorrectedReflectance_TrueColor", "2025-06-01",
|
|
place="Amazon Rainforest")
|
|
[image: true color view of the Amazon basin]
|
|
|
|
→ search_gibs_layers("vegetation")
|
|
Found 12 layer(s) matching 'vegetation':
|
|
MODIS_Terra_NDVI_8Day
|
|
MODIS/Terra Vegetation Index (NDVI), 8-Day — from 2000-02-18 (8-Day)
|
|
[has colormap]
|
|
MODIS_Terra_EVI_8Day
|
|
MODIS/Terra Enhanced Vegetation Index (EVI), 8-Day — from 2000-02-18 (8-Day)
|
|
[has colormap]
|
|
...
|
|
```
|
|
|
|
> **Assistant:** Here's the Amazon from MODIS Terra today — you can see the river system threading through dense canopy, with some cloud cover over the western basin. I also found vegetation index layers. Want me to overlay NDVI to show vegetation density, or check for fire/deforestation activity?
|
|
|
|
---
|
|
|
|
### Understanding what the colors mean
|
|
|
|
*Try this with the `layer_deep_dive` prompt: `layer_id="AIRS_L3_Surface_Air_Temperature_Daily_Day"`*
|
|
|
|
> **You:** What does the AIRS surface temperature layer actually show?
|
|
|
|
The assistant fetches metadata and the colormap interpretation:
|
|
|
|
```
|
|
→ get_layer_info("AIRS_L3_Surface_Air_Temperature_Daily_Day")
|
|
{"identifier": "AIRS_L3_Surface_Air_Temperature_Daily_Day",
|
|
"title": "Surface Air Temperature (Day, Daily)",
|
|
"instrument": "AIRS", "platform": "Aqua",
|
|
"period": "Daily", "ongoing": true,
|
|
"time": {"start": "2002-08-30", "end": null}}
|
|
|
|
→ explain_layer_colormap("AIRS_L3_Surface_Air_Temperature_Daily_Day")
|
|
Surface Air Temperature (K):
|
|
- dark blue = ~213 K (-60 C) -- extreme cold
|
|
- cyan = ~243 K (-30 C) -- severe cold
|
|
- green = ~268 K (-5 C) -- near freezing
|
|
- yellow = ~293 K (20 C) -- mild
|
|
- dark red = ~323 K (50 C) -- extreme heat
|
|
Color gradient runs from dark blues (low values) through greens to dark reds (high values).
|
|
(254 color stops total, 5 key values shown)
|
|
Transparent / no-data: No Data
|
|
|
|
→ get_legend("AIRS_L3_Surface_Air_Temperature_Daily_Day")
|
|
[image: horizontal color bar from blue to red, labeled 213K to 323K]
|
|
```
|
|
|
|
> **Assistant:** The AIRS instrument on NASA's Aqua satellite measures surface air temperature globally every day, and has been doing so since August 2002. The colormap runs from dark blue (around -60°C, polar regions) through greens (near freezing) to dark red (above 50°C, desert extremes). The 254 color stops give smooth gradation — areas with no valid retrieval show as transparent.
|
|
|
|
---
|
|
|
|
### Tracking change over time
|
|
|
|
*Try this with the `climate_monitor` prompt: `indicator="sea ice", location="Arctic", start_date="2025-03-01", end_date="2025-09-01"`*
|
|
|
|
> **You:** How has Arctic sea ice changed between winter and summer this year?
|
|
|
|
The assistant uses the `climate_monitor` workflow — search, verify dates, compare:
|
|
|
|
```
|
|
→ search_gibs_layers("sea ice concentration")
|
|
Found 6 layer(s) matching 'sea ice concentration':
|
|
AMSR2_Sea_Ice_Concentration_12km
|
|
AMSR2 Sea Ice Concentration, 12 km — from 2012-07-02 (Daily)
|
|
[has colormap]
|
|
...
|
|
|
|
→ explain_layer_colormap("AMSR2_Sea_Ice_Concentration_12km")
|
|
Sea Ice Concentration (%):
|
|
- dark blue = ~15%
|
|
- cyan = ~40%
|
|
- light grey = ~70%
|
|
- white = ~100%
|
|
Color gradient runs from dark blues (low values) through cyans to whites (high values).
|
|
Transparent / no-data: No Data, Land
|
|
|
|
→ compare_dates("AMSR2_Sea_Ice_Concentration_12km",
|
|
"2025-03-01", "2025-09-01",
|
|
bbox=[-180, 60, 180, 90])
|
|
[image: side-by-side comparison — March (left) vs September (right)]
|
|
```
|
|
|
|
> **Assistant:** The side-by-side view is striking. In March, the Arctic Ocean is almost entirely white (90-100% ice concentration), with the ice edge extending well into the Bering Sea and Barents Sea. By September, the ice has retreated dramatically — the white core is confined to a smaller region around the pole, with large stretches of dark blue (15-40%) and open water visible along the Northeast Passage and in Hudson Bay. The colormap tells us white = solid pack ice and dark blue = scattered ice at 15% concentration.
|
|
|
|
---
|
|
|
|
### Compositing layers to tell a story
|
|
|
|
*Try this with the `investigate_event` prompt: `event_type="wildfire", location="Los Angeles", date="2025-01-08"`*
|
|
|
|
> **You:** Can you show me how wildfire smoke from the 2025 LA fires affected air quality?
|
|
|
|
The assistant searches for complementary layers, checks dates, and builds a composite:
|
|
|
|
```
|
|
→ search_gibs_layers("aerosol")
|
|
Found 8 layer(s) matching 'aerosol':
|
|
MODIS_Terra_Aerosol_Optical_Depth
|
|
MODIS/Terra Aerosol Optical Depth — from 2000-02-24 (Daily)
|
|
[has colormap]
|
|
...
|
|
|
|
→ search_gibs_layers("fire thermal")
|
|
Found 4 layer(s) matching 'fire thermal':
|
|
MODIS_Fires_Terra
|
|
MODIS/Terra Thermal Anomalies and Fire — from 2000-02-24 (Daily)
|
|
[has colormap]
|
|
...
|
|
|
|
→ get_imagery_composite(
|
|
["MODIS_Terra_CorrectedReflectance_TrueColor",
|
|
"MODIS_Terra_Aerosol_Optical_Depth"],
|
|
"2025-01-08", place="Los Angeles")
|
|
[image: true color with aerosol optical depth overlay]
|
|
|
|
→ explain_layer_colormap("MODIS_Terra_Aerosol_Optical_Depth")
|
|
Aerosol Optical Depth:
|
|
- yellow-green = ~0.15 (clean air)
|
|
- orange = ~0.55 (moderate haze)
|
|
- dark red = ~1.0 (thick smoke/dust)
|
|
...
|
|
```
|
|
|
|
> **Assistant:** The composite overlay tells the story clearly. Over the LA basin, the true color base shows a visible smoke plume extending southwest over the Pacific. The aerosol optical depth overlay confirms it — the orange-to-red values (0.5-1.0) directly over the fire zone indicate thick particulate loading, fading to yellow-green (0.15, clean air) further out over the ocean. The fire thermal anomaly layer pinpoints the active burn areas as bright red hotspots in the foothills.
|
|
|
|
## Projections
|
|
|
|
| EPSG | Description | Use case |
|
|
|------|-------------|----------|
|
|
| 4326 | Geographic (WGS84) | Default — global coverage, most layers |
|
|
| 3857 | Web Mercator | Web map tiles, Leaflet/Mapbox integration |
|
|
| 3413 | Arctic Polar Stereographic | Arctic-focused imagery |
|
|
| 3031 | Antarctic Polar Stereographic | Antarctic-focused imagery |
|
|
|
|
## Development
|
|
|
|
```bash
|
|
uv sync --all-extras
|
|
|
|
# Lint
|
|
uv run ruff check src/ tests/
|
|
|
|
# Tests
|
|
uv run pytest
|
|
|
|
# Build
|
|
uv build
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
src/mcgibs/
|
|
server.py MCP server — tools, resources, prompts, middleware
|
|
client.py GIBS HTTP client — WMS, WMTS, colormaps, geocoding
|
|
capabilities.py WMTS GetCapabilities parser and layer search
|
|
colormaps.py Colormap XML parser and natural-language interpreter
|
|
models.py Pydantic models — Layer, BBox, GeoResult, ColormapEntry
|
|
constants.py API endpoints, projections, tile matrix definitions
|
|
geo.py Bounding box math and geocoding helpers
|
|
```
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE)
|
|
|
|
## Links
|
|
|
|
- [NASA GIBS](https://www.earthdata.nasa.gov/engage/open-data-services-software/earthdata-developer-portal/gibs-api)
|
|
- [GIBS API Documentation](https://nasa-gibs.github.io/gibs-api-docs/)
|
|
- [Worldview](https://worldview.earthdata.nasa.gov/) — NASA's browser-based GIBS viewer
|
|
- [FastMCP](https://gofastmcp.com/) — the MCP framework powering this server
|
|
- [Source](https://git.supported.systems/rpm/mcgibs)
|