era5

The ERA5 MCP server provides tools to fetch ERA5 climate data from the Copernicus CDS API, and to inspect downloaded NetCDF files. You can access three tools: fetch_era5_single_levels, which downloads monthly-mean ERA5 data for surface variables (e.g., 2m_temperature); fetch_era5_pressure_levels, which fetches ERA5 data on specified pressure levels (e.g., geopotential at 500 hPa) and can handle single or multiple years; and inspect_netcdf, which returns a summary of a NetCDF file's contents. By default, the server runs on localhost:8000 and exposes an OpenAPI specification at http://localhost:8000/openapi.json. You can integrate these tools with Gemini CLI, Claude, or other MCP-compatible clients to compose natural language requests such as “download January 2023 surface temperature” or “inspect the geopotential data file.”

Prerequisites:

• Python 3.8+ installed on your system
• Basic familiarity with Python virtual environments
• CDS API key configured via .cdsapirc (as described in the README) if you plan to fetch data from CDS

Step-by-step installation:

1. Clone the repository and navigate to the project directory.
2. (Optionally) Create and activate a Python virtual environment:

python -m venv venv
# macOS/Linux
source venv/bin/activate
# Windows
.\venv\Scripts\activate

3. Install Python dependencies from requirements.txt:

pip install -r requirements.txt

4. Ensure your CDS API key is configured. Create or update ~/.cdsapirc with:

url: https://cds.climate.copernicus.eu/api/v2
key: YOUR_UID:YOUR_API_KEY

5. Run the MCP server:

python era5_server.py

6. Open your MCP client (e.g., Gemini CLI, Claude) and point it to http://localhost:8000/openapi.json to discover the available tools.

Note: If you plan to download data, you must manually accept the CDS terms for the ERA5 datasets on their website before the server can access them. This configuration is done outside the MCP server following the CDS documentation.

Tips and common issues:

• The server uses a local OpenAPI spec at http://localhost:8000/openapi.json; ensure port 8000 is available or configure your client to target the correct address.
• To fetch multi-year data with fetch_era5_pressure_levels, you can pass a list of years, e.g., ['2020','2021','2022']. The tool will loop over the years and download corresponding files.
• When specifying output_filename, ensure the directory exists or the server has permission to create it.
• The inspect_netcdf tool returns a concise summary of dimensions, coordinates, and variables to help you validate the downloaded file before using it in downstream analysis.
• If you encounter CDS API authentication errors, verify that ~/.cdsapirc (or Windows equivalent) contains the correct URL and API key and that the environment running the server can access your home directory (or the path you place the config in).
• For single-level downloads, you can request variables such as '2m_temperature' for a given year and month; for pressure-levels, you can request variables like 'geopotential' or 'temperature' at a specific pressure level (e.g., 500 hPa).