ERA5 SMI

Calculate monthly soil moisture index (SMI) for any region based on ERA5-Land. Data comes in via an MCP server, the index is computed with a KDE transformation. Figures are generated using SKILLS.md files.

What you need

• uv

• A CDS account and API key in ~/.cdsapirc (see https://cds.climate.copernicus.eu/api-how-to)

Related MCP server: DMAP-AI MCP Server

Setup

cd mcp/era5-mcp && uv sync && cd ../..
uv sync

To use the MCP server, point your client at mcp.json in the root.

Run the MCP server in VS Code

1. Install the environments (first time only):

   cd mcp/era5-mcp && uv sync && cd ../..
   uv sync

2. Make the launcher executable (first time only):

   chmod +x mcp/era5-mcp/start_era5_mcp.sh

3. Register the server: create .vscode/mcp.json in the project root with the path to the launcher. A relative path works if you open VS Code from the project folder; use an absolute path otherwise:

   {
     "servers": {
       "era5": {
         "type": "stdio",
         "command": "/absolute/path/to/era5-smi-project/mcp/era5-mcp/start_era5_mcp.sh",
         "args": []
       }
     }
   }

4. Reload the window: Ctrl+Shift+P → "Developer: Reload Window". The server is listed under "MCP: Manage Servers" and should show as running (green).

5. Use it: ask the agent to call the tools fetch_era5_land_soil_moisture and extract_point_timeseries. The server only starts when the agent invokes it. Logs (with [DEBUG] lines) appear in the Output panel → MCP.

To verify the server works on its own, run bash mcp/era5-mcp/start_era5_mcp.sh in a terminal — it starts and waits on stdio (that's normal), Ctrl+C to stop.

Usage

1. Download data with the MCP tool fetch_era5_land_soil_moisture.

2. Extract your point with extract_point_timeseries.

3. Use the calculate-smi skill to compute the index (see skills/calculate-smi/SKILL.md).

4. Use the plot-smi skill to make the figures (see skills/plot-smi/SKILL.md).

The skills are the interface; never run the scripts under skills/*/scripts/ directly.

Layout

• AGENTS.md — instructions for running the pipeline

• pyproject.toml — environment for the skills (numpy, pandas, scipy, ...)

• mcp.json — config to connect an MCP client to the era5 server

• mcp/era5-mcp/ — MCP server, the only thing that talks to the CDS API

  • era5_server.py — the server and its MCP tools

  • start_era5_mcp.sh — launcher for the server

  • pyproject.toml — server environment (cdsapi, fastmcp, xarray)

• skills/

  • calculate-smi/ — turns a soil moisture CSV into an SMI series

    • SKILL.md — docs for the skill

    • scripts/calculate_smi.py — the script

  • plot-smi/ — turns an SMI CSV into figures

    • SKILL.md — docs for the skill

    • scripts/plot_smi.py — the script

• data/

  • raw/ — downloaded NetCDF files

  • processed/ — extracted CSVs and SMI CSVs

  • figures/ — output PNGs