Skip to content

v0.4.1 — initial public release

Choose a tag to compare

View all tags
@kuivi kuivi released this 19 May 14:53
· 6 commits to main since this release
v0.4.1
319babb

Initial public release.

`copernicus-mcp` is a self-hosted Model Context Protocol server that gives MCP-compatible LLM agents local, reproducible access to Copernicus environmental data — observations, reanalysis, forecasts, and climate indicators.

Backends

  • Copernicus Marine (CMEMS) — 1,251 datasets across 306 products in the bundled catalogue snapshot. Discovery + subset + native-file retrieval, sync or async.
  • Climate Data Store family (CDS / ADS / EWDS) — 164 datasets in the bundled snapshot. Queue-based asynchronous retrieval, offline discovery, T&C-not-accepted elicitation.

A single Personal Access Token works across CDS / ADS / EWDS under ECMWF's unified-token policy.

Tools

CMEMS (eleven): `marine_search_groups` → `marine_search_products` → `marine_search_datasets` (hierarchical discovery, no embeddings, no LLM at query time), `marine_describe_dataset`, `marine_get_coordinates`, `marine_estimate_subset`, `marine_subset_dataset`, `marine_list_files` → `marine_get_files`, `marine_check_status`, `marine_cancel_subset`.

CDS / ADS / EWDS (eight): `cds_search_groups`, `cds_search_datasets`, `cds_describe_dataset`, `cds_apply_constraints`, `cds_estimate_request`, `cds_submit_request`, `cds_check_request_status`, `cds_download_request_result`, `cds_cancel_request`.

Diagnostic: `copernicus_mcp_status`.

Install

```bash
python -m venv .venv && source .venv/bin/activate
pip install "copernicus-mcp[cmems,cds]"
copernicus-mcp status # verify
```

Conda / mamba alternative also documented in the README.

Highlights

  • Large data discipline: tools that return large data return `{filepath, uri, metadata, provenance}` — never inline bytes.
  • Confirmation gate: download size is estimated and large requests require explicit confirmation.
  • MD5-sealed provenance: every retrieval writes a sidecar JSON pinning the request shape, software versions, and file checksum.
  • Cross-platform cache paths: per-OS defaults via `platformdirs` (macOS `~/Library/Caches/...`, Windows `%LOCALAPPDATA%\...`, Linux XDG).
  • Smart filename + content_type: cached files for CDS / ADS / EWDS land with the real extension (`.nc` / `.grib` / `.zip`), with a magic-byte sniff to override the input-derived extension when ECMWF wraps a NetCDF request as ZIP.
  • Hierarchical search: two-hop deterministic routing over a curated 47-group manifest for CMEMS and a (domain, category) hierarchy for the CDS family. Auditable, offline, no vector index.
  • Async submit lifecycle: long CMEMS downloads can run as background tasks; agents poll via `marine_check_status` and `marine_cancel_subset`.

Tested

1427 unit tests. Integration suite exercises the live CMEMS + CDS APIs when `RUN_INTEGRATION_TESTS=1` is set with credentials.

License

BSD 3-Clause. Dependencies are EUPL-1.2 (`copernicusmarine`), Apache-2.0 (`cdsapi` and most others), MIT or BSD.

Upgrading

```bash
pip install --upgrade copernicus-mcp
```

Assets 2
Loading