# agro-weather-mcp

`agro-weather-mcp` is a public, open-source MCP server that gives LLMs compact,
agriculture-focused weather tools backed by the free Open-Meteo APIs. It uses
stdio only, needs no hosting, API key, or secret, and is intended for farmers,
agronomists, and agricultural software experiments.

## Install and run

With uv:

```sh
uvx --from git+https://github.com/rajshivang07/agro-weather-mcp agro-weather-mcp
```

For local development:

```sh
git clone https://github.com/rajshivang07/agro-weather-mcp
cd agro-weather-mcp
uv sync --extra dev
uv run agro-weather-mcp
```

## Who can use this and where

This server is useful anywhere an MCP-compatible assistant needs agriculture
weather context without building a custom Open-Meteo integration. It runs as a
local process over stdio, so users do not need to operate a web server, deploy
cloud infrastructure, or create an API key.

Typical users and environments include:

- Farmers who want a conversational way to check frost risk, recent water balance, or soil conditions for a field.
- Agronomists and crop advisors who need quick GDD calculations and weather summaries during field planning.
- Farm-management and precision-agriculture software teams that want reusable weather tools in an LLM workflow.
- Researchers and students prototyping crop-weather assistants without paying for a weather data service.
- Developers building local assistants in Claude Desktop, Claude Code, MCP Inspector, or another MCP-compatible client.
- Teams testing agricultural workflows before connecting them to their own field records, sensors, or farm databases.

Example workflows include:

- Geocode a farm, then inspect current and 48-hour soil conditions before discussing sowing timing.
- Calculate seasonal GDD from historical archive data and extend the range into the forecast when appropriate.
- Check the next 7 days for overnight frost exposure before recommending a field visit or crop-protection review.
- Compare precipitation with reference ET0 to identify periods that deserve closer soil-moisture monitoring.
- Use the five standardized tools as a weather layer inside a larger farm assistant, while keeping farm-specific decisions in the application that owns the field data.

This project is best suited to local development, personal assistants, demos,
education, research, and non-commercial prototypes that respect Open-Meteo's
free-tier terms and rate limits. It is not a replacement for a farm's weather
station, irrigation model, crop model, regulated advisory service, or local
agronomic expertise. Outputs are informational and should be reviewed before
being used in operational decisions.

### Claude Desktop

Add this entry to the Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "agro-weather": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/rajshivang07/agro-weather-mcp", "agro-weather-mcp"]
    }
  }
}
```

### Claude Code

```sh
claude mcp add agro-weather -- uvx --from git+https://github.com/rajshivang07/agro-weather-mcp agro-weather-mcp
```

## Tools

- `geocode_location`: find candidate places and coordinates.
- `get_growing_degree_days`: calculate capped, modified-average GDD across past and forecast dates.
- `get_frost_risk`: summarize overnight minimums, threshold hours, and risk levels.
- `get_water_balance`: compare precipitation with FAO-56 reference ET0 and explain dryness.
- `get_soil_conditions`: summarize current and 48-hour soil temperature and moisture by depth.

## Tool behavior and expected results

The tools are task-oriented interpretations of Open-Meteo data. The rule-based
notes and risk labels below are generated by this MCP server. They are not text
provided by the Open-Meteo APIs.

Every tool response includes the resolved date range, timezone, units, and
`data_source: "Open-Meteo (CC BY 4.0)"`. Coordinates are validated before a
request is made. Invalid coordinates, dates, date ranges, counts, or forecast
horizons return actionable tool errors.

### `geocode_location`

Input:

```json
{
  "name": "Davis",
  "country_code": "US",
  "count": 3
}
```

`name` is required. `country_code` is optional and must be a two-letter ISO
country code. `count` defaults to 3 and must be between 1 and 10.

The result contains candidate places with:

- `name`
- `admin_area`
- `country`
- `latitude` and `longitude` in degrees
- `elevation` in metres
- `timezone` as an IANA timezone name

This tool has no user-supplied dates, so its resolved date range is the current
date. Use the returned coordinates with the other tools.

### `get_growing_degree_days`

Input:

```json
{
  "lat": 38.54,
  "lon": -121.74,
  "start_date": "2026-04-01",
  "end_date": "2026-04-30",
  "base_temp_c": 10.0,
  "upper_cap_c": 30.0,
  "method": "modified_avg"
}
```

Dates use inclusive `YYYY-MM-DD` format. The range can be at most 366 days.
Past dates use the archive endpoint, future dates use the forecast endpoint,
and a range crossing today is split and merged automatically. Future dates are
limited by the forecast horizon of 16 days from today.

The current method is `modified_avg`. For each day, Tmin and Tmax are clamped
to the inclusive range `[base_temp_c, upper_cap_c]`, then calculated as:

```text
GDD = ((clamped Tmax + clamped Tmin) / 2) - base temperature
```

The response contains total accumulated GDD in degree-days. For ranges of 31
days or fewer it also contains daily values. Longer ranges contain weekly GDD
summaries instead. Missing daily temperatures produce a null daily value and
are excluded from the total.

### `get_frost_risk`

Input:

```json
{
  "lat": 35.68,
  "lon": 139.65,
  "days": 7,
  "threshold_c": 0.0
}
```

`days` must be between 1 and 16. `threshold_c` is in degrees Celsius. The
server requests hourly `temperature_2m` forecasts and returns each detected
night's minimum temperature and the number of hours below the threshold.

Risk is assigned using these server rules:

- `none`: zero hours below the threshold
- `low`: minimum temperature is above `threshold_c - 2 °C`
- `moderate`: minimum temperature is above `threshold_c - 5 °C`
- `high`: minimum temperature is at or below `threshold_c - 5 °C`

The result is forecast-only and covers the current date through the requested
number of forecast days in the resolved local timezone.

### `get_water_balance`

Input:

```json
{
  "lat": 52.52,
  "lon": 13.41,
  "start_date": "2026-06-01",
  "end_date": "2026-06-30"
}
```

Dates use inclusive `YYYY-MM-DD` format and the range can be at most 366 days.
The server combines daily precipitation and
`et0_fao_evapotranspiration`, both in millimetres, using:

```text
water balance = precipitation - reference ET0
```

The response contains total precipitation, total ET0, total balance, weekly
balance summaries, and a server-generated `dryness_note`:

- Balance at least 10 mm: `Likely water surplus`
- Balance greater than -10 mm: `Roughly balanced`
- Balance at or below -10 mm: `Likely drying conditions; monitor soil moisture and irrigation needs`

The note is a simple weather-based interpretation. It is not an irrigation
recommendation and does not model crop type, soil storage, runoff, or field
conditions.

### `get_soil_conditions`

Input:

```json
{
  "lat": 42.36,
  "lon": -71.06
}
```

The server requests current and approximately 48 hours of forecast data for
the available depths:

- `0_to_7cm`
- `7_to_28cm`
- `28_to_100cm`
- `100_to_255cm`

Soil temperature is returned in degrees Celsius. Soil moisture is volumetric
water content in `m³/m³`. Each depth contains current values plus next-48-hour
minimum, maximum, and average statistics for both variables.

The response also contains this clearly labeled rough sowing guide:

```text
Many crops prefer about 8-10 °C at seed depth.
```

This is not a crop-specific threshold or agronomic recommendation. Actual
sowing decisions should use crop-specific local guidance, soil conditions, and
field observations.

Example prompts:

- “Find the three closest matches for Davis, California, then calculate April GDD using a 10 C base.”
- “What is the frost risk for this location over the next seven days at 0 C?”
- “Was the last month wetter or drier than reference crop demand?”
- “What are the current and next-48-hour soil conditions at this location?”

## Data and limits

Data comes from Open-Meteo, attributed as **Open-Meteo (CC BY 4.0)**. The archive
tool uses ERA5-style historical data and forecast requests use the Open-Meteo
forecast API. Open-Meteo's free tier is for non-commercial use and has rate
limits. Check the Open-Meteo terms and documentation for current limits before
deploying repeated or commercial workloads.

Outputs are informational and are not agronomic advice. Weather, soil, crop,
and management decisions require local expertise and appropriate observations.

## Testing with MCP Inspector

Run the server through the MCP Inspector with the project command configured as
`uv run agro-weather-mcp` and transport set to stdio. The Inspector can list the
five tools and invoke them with JSON arguments without needing a hosted endpoint.

## Development

```sh
uv sync --extra dev
uv run ruff check .
uv run ruff format --check .
uv run pytest
```

Live smoke tests are excluded by default. Set `RUN_LIVE=1` to run them.