OpenLandMap MCP Server

MCP Server for the OpenLandMap STAC catalog — full access to global geospatial environmental data for AI agents.

Overview

OpenLandMap provides 104+ collections of global environmental data as Cloud-Optimized GeoTIFFs (COG), covering:

Installation

cd openlandmap-mcp

# Install with uv
uv pip install -e .

# Or run directly (uv resolves dependencies automatically)
uv run openlandmap-mcp

Configuration

Prerequisites: uv must be installed and available in PATH.

Claude Code

Add to .claude/settings.json (project-level) or ~/.claude/settings.json (global):

{
  "mcpServers": {
    "openlandmap": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/openlandmap-mcp", "openlandmap-mcp"]
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "openlandmap": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/openlandmap-mcp", "openlandmap-mcp"]
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json (global) or .gemini/settings.json (project-level):

{
  "mcpServers": {
    "openlandmap": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/openlandmap-mcp", "openlandmap-mcp"],
      "timeout": 60000
    }
  }
}

After configuration, verify with the /mcp command inside Gemini CLI to list connected servers and available tools.

ChatGPT Desktop

ChatGPT supports MCP servers exclusively via remote HTTP/SSE transport — local stdio processes are not supported. You need to expose the server over HTTP first.

Step 1 — Start the server with SSE transport:

uv run openlandmap-mcp --transport sse --port 8811

Step 2 — Expose locally (for development) or deploy publicly:

For local development, use a tunnel like ngrok:

ngrok http 8811
# Example output: https://abc123.ngrok.app

For production, deploy behind a reverse proxy with a public HTTPS URL.

Step 3 — Register in ChatGPT Desktop:

1. Open Settings → Apps & Connectors → Advanced Settings
2. Enable Developer Mode
3. Go to Settings → Connectors → Create
4. Fill in:
   • Name: OpenLandMap
   • Connector URL: https://abc123.ngrok.app/mcp (or your public URL)
   • Authentication: None (or configure as needed)

Note: ChatGPT does not support local config files for MCP. All registration is done through the UI. The server must be reachable over HTTPS.

Cursor / VS Code

Add to .cursor/mcp.json (Cursor) or .vscode/mcp.json (VS Code):

{
  "mcpServers": {
    "openlandmap": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/openlandmap-mcp", "openlandmap-mcp"]
    }
  }
}

Compatibility Matrix

Capabilities

1. Catalog Discovery

Browse and search the entire OpenLandMap catalog.

catalog_info()

Returns root catalog metadata: ID, description, STAC version, total collection count.

"What data is available on OpenLandMap?"

list_collections(theme?, keyword?, limit?)

List collections with optional filters by theme alias or keyword search across titles, descriptions, and keywords.

"List all soil collections"
→ list_collections(theme="soil")

"Find collections related to organic carbon"
→ list_collections(keyword="organic carbon")

"Show the first 5 vegetation datasets"
→ list_collections(theme="vegetation", limit=5)

Available theme aliases: soil, vegetation, land_cover, climate, terrain, water, atmosphere, population

get_collection_schema(collection_id)

Returns the full schema of a collection: asset type definitions (MIME types, roles), STAC extensions used, spatial/temporal extent, contact info, style URLs (SLD/QML), and related links.

"Show me everything about the organic carbon collection"
→ get_collection_schema("organic.carbon_usda.6a1c")

discover_data_for_topic(topic)

Natural language search across all collection titles, descriptions, and keywords. Returns results ranked by relevance score.

"Find data about deforestation in the Amazon"
→ discover_data_for_topic("Amazon deforestation forest loss")

"What datasets exist for air quality analysis?"
→ discover_data_for_topic("air quality NO2 aerosol")

2. Collection Operations

Analyze, compare, and explore collections in depth.

compare_collections(collection_ids)

Side-by-side comparison of 2–10 collections: temporal coverage, resolution, units, keywords, and theme.

"Compare soil organic carbon and pH datasets"
→ compare_collections(["organic.carbon_usda.6a1c", "ph.h2o_usda.4c1a2a"])

get_collection_temporal_stats(collection_id)

Temporal statistics: earliest/latest dates, item count, year-by-year distribution, and median update interval.

"How often is the EVI dataset updated?"
→ get_collection_temporal_stats("evi_mod13q1.tmwm.inpaint")

find_related_collections(collection_id)

Finds collections sharing the same theme or native category. Useful for discovering complementary datasets.

"What other datasets are related to land surface temperature?"
→ find_related_collections("lst_mod11a2.daytime")

get_soil_collections()

Shortcut returning all soil-related collections (bulk density, organic carbon, pH, sand/clay/silt, texture, water content, taxonomy).

"List all available soil datasets"
→ get_soil_collections()

get_vegetation_collections()

Shortcut returning all vegetation-related collections (EVI, FAPAR, forest cover, plant functional types).

"What vegetation indices are available?"
→ get_vegetation_collections()

get_land_cover_collections()

Shortcut returning all land cover/land use collections (classification, cropland, pasture, urban, change detection).

"Show me land cover datasets"
→ get_land_cover_collections()

3. Item Search & Access

Search and retrieve individual temporal snapshots within collections.

search_items(collection_id, bbox?, datetime_range?, limit?, offset?)

Search items with spatial (bounding box) and temporal (ISO 8601 interval) filters. Supports pagination.

"Find organic carbon data for the Cerrado region"
→ search_items("organic.carbon_usda.6a1c", bbox=[-60.47, -24.68, -41.28, -2.33])

"Get EVI data from 2015 to 2020"
→ search_items("evi_mod13q1.tmwm.inpaint", datetime_range="2015-01-01/2020-12-31", limit=10)

"Show all items in the land cover collection"
→ search_items("land.cover_esacci.lc.l4", limit=50)

get_item_detail(collection_id, item_id)

Full item details: geometry (GeoJSON), bounding box, temporal range, all assets with resolved URLs, MIME types, file sizes, and checksums.

"Show full details for the 2018 organic carbon item"
→ get_item_detail("organic.carbon_usda.6a1c", "organic.carbon_usda.6a1c_19500101_20171231")

list_items_temporal(collection_id)

Lists all items sorted chronologically. Shows the complete temporal coverage and update pattern of a dataset.

"What time periods are available for EVI?"
→ list_items_temporal("evi_mod13q1.tmwm.inpaint")

find_items_by_point(lon, lat, collection_ids?)

Given a WGS84 coordinate, finds all items covering that point across one or more collections.

"What data is available for Brasília?"
→ find_items_by_point(-47.9, -15.8)

"Find soil data at this location"
→ find_items_by_point(-47.9, -15.8, ["organic.carbon_usda.6a1c", "ph.h2o_usda.4c1a2a"])

4. Asset Access & Download

Resolve URLs and generate download instructions for data files.

get_asset_url(collection_id, item_id, asset_key)

Resolves the full S3 URL for a specific asset. Returns MIME type, roles, COG status, file size, checksum, and S3 bucket/key.

"Get the URL for the 0cm depth organic carbon layer"
→ get_asset_url("organic.carbon_usda.6a1c", "organic.carbon_usda.6a1c_19500101_20171231", "organic.carbon_usda.6a1c_m_250m_b0cm")

list_assets_for_item(collection_id, item_id)

Lists all assets (data layers, thumbnails, style files) with complete metadata for each.

"What files are available in this item?"
→ list_assets_for_item("organic.carbon_usda.6a1c", "organic.carbon_usda.6a1c_19500101_20171231")

get_all_data_assets(collection_id, item_id)

Filters to only data assets (role="data"), excluding thumbnails, QML, and SLD files. Returns direct COG URLs.

"Give me only the data layers, not the styles"
→ get_all_data_assets("organic.carbon_usda.6a1c", "organic.carbon_usda.6a1c_19500101_20171231")

get_asset_download_info(collection_id, item_id, asset_key)

Returns the direct URL plus ready-to-use commands and code snippets:

• curl command for download
• wget command for download
• Python snippet using rasterio (streaming, no download needed)
• R snippet using terra (streaming, no download needed)

"How do I access the soil carbon data programmatically?"
→ get_asset_download_info("organic.carbon_usda.6a1c", "organic.carbon_usda.6a1c_19500101_20171231", "organic.carbon_usda.6a1c_m_250m_b0cm")

get_visualization_assets(collection_id, item_id)

Returns visualization-related assets: thumbnails (PNG), QGIS layer styles (QML), and WMS style descriptors (SLD).

"Get the QGIS style file for this layer"
→ get_visualization_assets("organic.carbon_usda.6a1c", "organic.carbon_usda.6a1c_19500101_20171231")

5. Spatial Queries

Work with geographic regions and spatial coverage.

get_bbox_for_region(region_name)

Returns the WGS84 bounding box [west, south, east, north] for a named region. Supports ~50 regions:

• Countries: brazil, usa, china, india, australia, germany, france, japan, mexico, argentina, colombia, south_africa, kenya, indonesia, etc.
• Brazilian states: goias, mato_grosso, para, minas_gerais, sao_paulo, bahia, amazonas, tocantins, maranhao, rondonia, acre, roraima, amapa, etc.
• Brazilian biomes: cerrado, amazon, amazonia_legal, caatinga, pantanal, mata_atlantica, pampa
• Continents/regions: south_america, north_america, europe, africa, asia, southeast_asia, oceania, middle_east, global

"What's the bounding box for the Cerrado biome?"
→ get_bbox_for_region("cerrado")
# Returns: {"region": "cerrado", "bbox": [-60.47, -24.68, -41.28, -2.33]}

"Get the bbox for Goiás state"
→ get_bbox_for_region("goias")

find_collections_for_bbox(bbox, theme?)

Finds all collections whose spatial extent intersects the given bounding box. Optionally filters by theme.

"What soil data covers the Cerrado?"
→ find_collections_for_bbox([-60.47, -24.68, -41.28, -2.33], theme="soil")

"Find all datasets available for Southeast Asia"
→ find_collections_for_bbox([92.0, -11.0, 141.0, 28.0])

get_collection_spatial_coverage(collection_id)

Returns full spatial coverage: bounding box, GeoJSON polygon of the extent, ground sample distance (resolution in meters), and CRS.

"What is the spatial resolution of the elevation model?"
→ get_collection_spatial_coverage("dtm.bareearth_ensemble")

6. Analysis & Code Generation

Discover data by topic, analyze temporal coverage, and generate ready-to-use code.

get_data_timeline(collection_ids)

Generates a structured timeline showing data availability across 1–10 collections. Useful for planning multi-temporal analyses.

"Show me when soil and vegetation data overlap"
→ get_data_timeline(["organic.carbon_usda.6a1c", "evi_mod13q1.tmwm.inpaint"])

find_overlapping_datasets(collection_id, start_year, end_year)

Finds all other collections with temporal overlap in the given period. Useful for multi-variable correlation studies.

"What datasets overlap with land cover data between 2010 and 2020?"
→ find_overlapping_datasets("land.cover_esacci.lc.l4", 2010, 2020)

get_stac_item_as_geojson(collection_id, item_id)

Returns the item as a pure GeoJSON Feature, ready for use in any GIS tool, web map, or geospatial pipeline.

"Export this item as GeoJSON"
→ get_stac_item_as_geojson("organic.carbon_usda.6a1c", "organic.carbon_usda.6a1c_19500101_20171231")

build_python_snippet(collection_id, item_id, asset_key, operation)

Generates a ready-to-run Python code snippet using rasterio and matplotlib.

Operations: open, info, plot, clip_bbox, stats, export_csv

"Generate Python code to plot organic carbon data"
→ build_python_snippet("organic.carbon_usda.6a1c", "organic.carbon_usda.6a1c_19500101_20171231", "organic.carbon_usda.6a1c_m_250m_b0cm", "plot")

"Generate code to compute statistics"
→ build_python_snippet(..., operation="stats")

"Generate code to clip to a bounding box"
→ build_python_snippet(..., operation="clip_bbox")

build_r_snippet(collection_id, item_id, asset_key, operation)

Generates a ready-to-run R code snippet using terra and sf.

Operations: open, info, plot, clip_bbox, stats, export_csv

"Generate R code to open and plot this raster"
→ build_r_snippet("organic.carbon_usda.6a1c", "organic.carbon_usda.6a1c_19500101_20171231", "organic.carbon_usda.6a1c_m_250m_b0cm", "plot")

MCP Resources

Static data accessible via URI patterns:

MCP Prompts

Pre-built workflow templates for common analysis patterns:

Usage Examples

"What data is available on OpenLandMap?"
"List all soil datasets"
"Find collections about organic carbon"
"Show the temporal coverage of evi_mod13q1.tmwm.inpaint"
"Find vegetation data for the Cerrado between 2015 and 2020"
"Generate a Python snippet to access EVI data"
"Compare soil collections: organic.carbon vs ph.h2o"
"What is the spatial resolution of the elevation dataset?"
"Find datasets that overlap temporally with land cover between 2010-2020"
"Generate R code to plot soil organic carbon"
"What data is available at coordinates -47.9, -15.8?"
"Export this STAC item as GeoJSON for use in QGIS"
"How do I download the bulk density dataset with curl?"
"Show me the QGIS style file for the pH collection"

Architecture

• Static catalog: Data is served from S3 (Wasabi) as static STAC JSONs — no server-side search API
• In-memory cache: Configurable TTL per resource type (1h catalog, 30min collections, 10min items)
• Lazy loading: Collections fetched on demand with concurrent batch fetch (semaphore-limited) when global filtering is needed
• No native dependencies: Pure Python and pre-built wheels only (no GDAL/GEOS compilation required)
• Retry with backoff: Automatic retry (3 attempts, exponential delays 1s/2s/4s) for all HTTP requests
• Thundering herd protection: Per-key async locks prevent duplicate fetches for the same resource

License

OpenLandMap data is distributed under CC-BY-SA-4.0.