Copernicus Earth Observation MCP Server

An MCP server for Copernicus Sentinel
data from the Copernicus Data Space Ecosystem
(CDSE): search products and Sentinel-1 SLC bursts, inspect metadata, and
download data with background jobs.

• Missions: Sentinel-1, -2, -3, -5P, -6
• Python: 3.13+
• Auth: token-first (refresh token or access token), password grant as
  fallback

Features

Search & discovery

• Search by point / bounding box / polygon (GeoJSON or WKT), date range, and
  mission-specific filters (product type, processing level, satellite, cloud
  cover, orbit direction, relative orbit, Sentinel-2 tile, S1 mode/swath/
  polarisation, or any catalogue attribute)
• Real server-side filtering (cloud cover and attributes are filtered by the
  API, not silently dropped)
• Recent products, temporal coverage analysis, full product metadata with
  checksums and quicklook URLs

Sentinel-1 SLC bursts

• Search bursts by parent product, burst/absolute burst id, subswath,
  polarisation, mode, orbit, datatake, or area + time
• Download bursts as zip via the CDSE on-demand extraction service
  (background job)

Downloads

• Background download jobs (products, S1 native archives, quicklooks, bursts)
  with status, progress, speed, and cancellation — no more MCP tool timeouts
  on multi-GB products
• Resumable downloads (HTTP Range), MD5 checksum verification
• Quicklooks download synchronously (small, fast previews)

File management

• List / statistics / cleanup of downloaded files, all confined to the
  configured download root (dry-run by default)

Installation

git clone <repository-url>
cd copernicus-mcp

uv venv -p 3.13          # or 3.14
uv pip install -e ".[dev]"

A free account is required for downloads: https://dataspace.copernicus.eu/

Authentication

Token-based authentication is primary. Configure one of:

Search works without authentication; downloads require a token.

Running the server

copernicus-mcp                          # stdio transport (default)
python -m copernicus_mcp                # equivalent

copernicus-mcp --transport http --host 127.0.0.1 --port 8000
copernicus-mcp --log-level DEBUG --version

MCP client configuration (stdio)

{
  "mcpServers": {
    "copernicus": {
      "command": "copernicus-mcp",
      "env": {
        "COPERNICUS_REFRESH_TOKEN": "<your-refresh-token>"
      }
    }
  }
}

Tools

Search & discovery

Sentinel-1 SLC bursts

Downloads

File management

Typical workflow

1. search_products(geometry=[2.29, 48.85, 2.30, 48.86], mission="sentinel-2",
                   start_date="2024-06-01", end_date="2024-06-30",
                   max_cloud_cover=20)
2. get_product_details(image_id="<uuid from results>")
3. download_quicklook(image_id="<uuid>")            # fast preview
4. start_download(image_id="<uuid>", kind="product") # background job
5. get_download_status(job_id="<job_id>")

Configuration

Architecture

copernicus_mcp/
├── server.py        # FastMCP wiring + CLI
├── app.py           # service container (built once per process)
├── config.py        # settings from environment
├── auth.py          # token manager (refresh/access token, password)
├── errors.py        # exception hierarchy
├── odata/
│   ├── query.py     # pure query builders (dates, geometry, filters)
│   ├── models.py    # Product / Burst / Asset / Checksum models
│   └── client.py    # async OData client (paging, retries)
├── downloads/
│   ├── manager.py   # streaming, resume, checksums, path confinement
│   ├── jobs.py      # background job manager
│   └── service.py   # executes download jobs
└── tools/           # MCP tool implementations

Notes:

• Queries follow the official CDSE OData syntax; see
  docs/odata-quickref.md and the documentation
  snapshots in docs/reference/.
• Background jobs are in-memory: they do not survive a server restart
  (partial files stay on disk and are resumed on retry).

Development

uv pip install -e ".[dev]"
pytest                 # unit + tool tests (no network; httpx.MockTransport)
ruff check copernicus_mcp tests

Docker

docker build -t copernicus-mcp .
docker run -i --rm -e COPERNICUS_REFRESH_TOKEN=<token> copernicus-mcp   # stdio
docker run --rm -e COPERNICUS_REFRESH_TOKEN=<token> \
  -v $PWD/downloads:/data/downloads -e COPERNICUS_DOWNLOAD_DIR=/data/downloads \
  copernicus-mcp --transport http --host 0.0.0.0 --port 8000

API notes and limitations

• Scope: Sentinel collections only (SENTINEL-1/2/3/5P/6). Other CDSE
  collections (CCM, CLMS, COP-DEM, Landsat, ...) exist in the catalogue but
  are not exposed here.
• Native archives (compressed): Sentinel-1 RAW/GRD/SLC, one month after
  publication only.
• Burst downloads use the CDSE on-demand extraction service and may take a
  while; if the service is unavailable, get_burst_details provides the
  S3Path/ByteOffset/Lines/SamplesPerBurst values needed for GDAL-based
  extraction (see the Sentinel-1 SLC Bursts documentation).
• Full products can be several GB — prefer quicklooks for previews.

License

LGPL-3.0-or-later (see LICENSE).

Acknowledgments

• ESA and the Copernicus programme
• The Copernicus Data Space Ecosystem for API access