# 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/mcp/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/mcp/mcgibs)