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)

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