eea-climate-data-mcp

Schema-aware, read-only access to European climate data published through the public Discodata service of the European Environment Agency (EEA).

This MVP is a conditional go. It supports the verified GHG Inventory and Policies and Measures databases. A current projections database was not visible in Discodata metadata during the 2026-07-19 spike, so WEM/WAM comparison is not claimed.

Install

Install the CLI and MCP server as isolated commands:

uv tool install eea-climate-data-mcp
eu-climate --help

Development checkout:

uv sync --extra test
uv run eu-climate databases list
uv run eea-climate-data-mcp

The MCP command uses stdio transport. No credentials are required.

Claude Code:

claude mcp add --scope user eu-climate -- uvx eea-climate-data-mcp

Codex CLI:

codex mcp add eu-climate -- uvx eea-climate-data-mcp

CLI examples

uv run eu-climate series emissions --country DE --sector total \
  --accounting-scope without_lulucf --start-year 1990

uv run eu-climate sectors search transport
uv run eu-climate series emissions --country HU --sector 1.A.3 --start-year 1990

uv run eu-climate measures list --country Hungary --status Implemented --sector Transport
uv run eu-climate measures get --country Hungary --measure-id 4

uv run eu-climate tables describe \
  --database GHG_Inventory --version latest --table ghg_value

uv run eu-climate values distinct \
  --database GHGPAMS --version latest \
  --table annexIX_flat_view_PaMs_elasticsearch --column Country

uv run eu-climate sql validate --query-file examples/country_inventory_counts.sql
uv run eu-climate sql run --query-file examples/country_inventory_counts.sql \
  --max-rows 100 --page-size 100

All execution paths use the same service and SQL guardrails. Queries must be one parsed SELECT, fully qualify every table as [database].[version].[table], use allowlisted databases and versions, and remain within the requested bound. DDL, DML, CTEs, SELECT INTO, system schemas, and unaliased computed columns are rejected.

Verified source model

Country identifiers differ between datasets: inventory uses codes such as DE, FR, and HU, while Policies and Measures uses labels such as Germany, France, and Hungary. Use metadata discovery or values distinct before constructing cross-domain queries. EUA is an aggregate, not a country.

latest is mutable. Use a concrete version or revision for reproducible analysis when the upstream exposes one. The latest inventory year is a published reporting year, not a real-time emissions figure.

The get_emissions_series MCP tool and series emissions CLI command resolve the appropriate inventory variable and sort results client-side because upstream rejects ORDER BY on some ghg_value queries. sector accepts total or an IPCC sector code at any depth (1, 1.A, 1.A.3); discover codes with search_emission_sectors/describe_emission_sector (sectors search|describe). Parent sectors already include their children — never sum a sector with its parent or children.

The list_measures/get_measure tools (measures list|get CLI) expose the Policies and Measures database as a searchable descriptive catalogue. Structured ex-ante and ex-post effect values are sparse (several countries, including Hungary, report none), so get_measure returns explicit quantification semantics — reported vs not_reported — and missing values must not be read as zero impact. The catalogue is deliberately not a ranking or impact-estimation source. Every result includes a query hash, retrieval time, table references, reporting status, source links, and warnings.

Machine-readable output goes to stdout and diagnostics to stderr. Exit codes:

docs/RECIPES.md contains six reproducible investigation recipes (trend, sectoral change, road-transport contribution, PaMs reporting completeness, sector quantification gaps, trend × measure stock) with exact commands, formulas, query hashes, and caveats.

See docs/SPIKE-REVIEW.md for evidence, limitations, and next scope. The original Hungary-focused brief is retained as historical context in docs/SPIKE-hun-climate-policy-mcp.md.

Development

uv run pytest
uv run ruff format --check src tests
uv run ruff check src tests
uv run mypy src tests
uv run python scripts/live_smoke.py

The live smoke suite is intentionally small and read-only.

Release

Maintainers release from a clean, synchronized main branch:

scripts/release patch

The helper bumps the version, commits and pushes it, then creates a GitHub Release. The release workflow builds the distributions and publishes them to PyPI through trusted publishing.

Configuration