mcgibs/README.md

mcgibs

NASA Earth science visualizations for LLMs.

An MCP server that connects language models to NASA GIBS (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

uvx mcgibs

Add to Claude Code

claude mcp add mcgibs -- uvx mcgibs

Local development

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:

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

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

Links

• NASA GIBS
• GIBS API Documentation
• Worldview — NASA's browser-based GIBS viewer
• FastMCP — the MCP framework powering this server
• Source