GeoCroissant Server

Model Context Protocol (MCP) server for GeoCroissant and its geospatial extension.

Features

• EO dataset discovery - keyword/topic search over STAC collections and spatial scene search (bbox + datetime + cloud cover) against the live Element84 Earth Search API (https://earth-search.aws.element84.com/v1, AWS Open Data), with sensor-modality classification (optical / radar / elevation) and theme shortcuts (flood, wildfire, ndvi, dem, ...).
• STAC -> GeoCroissant generation - turns live search results into a validated GeoCroissant document: schema.org coverage, CRS, band configuration & spectral metadata derived from eo:bands (converted from micrometers to nanometers), distribution FileObjects for direct asset URLs, and a RecordSet embedding one row per scene.
• Official validator as a tool - structured pass/fail reports with errors and warnings from mlcroissant (the same engine as mlcroissant validate).
• Deep inspection - core metadata plus every GeoCroissant property: CRS, spatial/temporal resolution, band configuration, spectral band metadata, record endpoint, spatial index/bias/sampling strategy.
• Structure graph extraction - exposes the directed multigraph the library builds internally (Metadata / FileObject / FileSet / RecordSet / Field nodes; source, join and containment edges).
• Record materialization - executes the real operation graph (downloads, extracts, transforms) to preview actual records, exactly like Dataset.records(...) in Python.
• Validated scaffolding - generates standards-conformant GeoCroissant JSON-LD from structured parameters and checks it through the real validator.
• Built-in spec reference - namespaces, all geocr: properties with domains/cardinality, canonical @context, sample document and Python API.

Tools

Adding a catalog

The registry is data-driven (src/geocr_mcp_server/config/catalogs.yaml): each catalog is an entry with its STAC URL, curated collections per modality, plus shared topics and modality keyword hints. To register another catalog without touching code:

1. Copy the YAML somewhere and append your catalog under catalogs (and any theme mappings under topics).
2. Point the environment variable at it:

"env": { "GEOCR_CATALOGS_CONFIG": "/path/to/catalogs.yaml" }

The loader validates that topic references exist in some catalog's collection lists, so typos fail fast at startup.

Recommended agent workflow

discovery:  list_eo_catalogs -> search_eo_datasets("burn scar", modality=optical)
            -> search_eo_scenes(bbox=[...], datetime_range=...)
metadata:   create_geocroissant_from_stac(...)  # validated output + optional file
consuming:  inspect_geocroissant -> get_records_preview -> extract_distribution_urls
authoring:  create_geocroissant_scaffold -> edit -> validate_croissant

[!TIP] Remote Client / Cloud Usage: When connected to a remote hosted server (e.g. on Render), the generated GeoCroissant document is returned directly inline under json_ld in the tool response. Remote agents / IDE clients should write json_ld straight to their local workspace rather than attempting to read path from the remote container.

Installation

No clone needed - pip/uvx fetch both geocr-mcp and its mlcroissant dependency straight from GitHub. Cloning is only required for development.

pip

pip install git+https://github.com/HarshShinde0/geocr_mcp.git@main

The single dependency mlcroissant is pulled automatically from the GeoCroissant fork:

pip install git+https://github.com/HarshShinde0/croissant.git@main#subdirectory=python/mlcroissant

uv / uvx (recommended for clients)

uvx --from "geocr-mcp @ git+https://github.com/HarshShinde0/geocr_mcp.git@main" geocr-mcp-server

Docker

docker build -t geocr-mcp-server .
# stdio (local clients):
docker run -i --rm geocr-mcp-server
# hosted (HTTP transports):
docker run -p 8000:8000 geocr-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

Client configuration

No clone needed - clients install (and cache) both packages directly from GitHub via uvx.

{
  "mcpServers": {
    "geocr": {
      "command": "uvx",
      "args": [
        "--from", "geocr-mcp @ git+https://github.com/HarshShinde0/geocr_mcp.git@main",
        "geocr-mcp-server"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

{
  "mcp": {
    "servers": {
      "geocr": {
        "command": "uvx",
        "args": [
          "--from", "geocr-mcp @ git+https://github.com/HarshShinde0/geocr_mcp.git@main",
          "geocr-mcp-server"
        ],
        "env": {
          "FASTMCP_LOG_LEVEL": "ERROR"
        }
      }
    }
  }
}

git clone https://github.com/HarshShinde0/geocr_mcp.git   # or this monorepo

{
  "mcpServers": {
    "geocr": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/geocr_mcp",
        "run", "geocr-mcp-server"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

geocr-mcp-server --transport streamable-http --host 0.0.0.0 --port $PORT

{
  "mcpServers": {
    "geocr-remote": {
      "url": "https://geocr-mcp-server.onrender.com/mcp"
    }
  }
}

Environment variables

Security considerations

• The server performs network requests only when a tool input references a URL or when materializing records from remote distributions (get_records_preview). Keep limit small in untrusted contexts.
• Generated files are always written inside GEOCR_OUTPUT_DIR; path traversal is blocked by reducing filenames to their basename.
• Run containers as non-root (the provided Dockerfile already does).

Development

cd geocr_mcp
uv venv && uv sync --all-groups     # or: python -m pip install -e ".[dev]"
uv run pytest --cov --cov-branch    # unit tests (no network required)
uv run ruff check src tests         # lint (same rules as awslabs/mcp)
npx @modelcontextprotocol/inspector geocr-mcp-server   # interactive debugging