# agrisignal-mcp

An MCP server for farm and land decision support, built entirely on free, keyless public data:
[Open-Meteo](https://open-meteo.com) (weather, soil moisture/temperature, evapotranspiration) and
[SoilGrids](https://soilgrids.org) (ISRIC's global 250m-resolution soil map). No API keys, no signup,
no OAuth — every tool works out of the box.

Unlike general-purpose weather/soil API wrappers, this server doesn't just hand back raw data — it
synthesizes weather and soil into farming decisions: whether to irrigate and how much, frost and heat
stress risk windows, growing degree day accumulation for predicting crop development, and drought
tracking. The goal is to be useful to someone without access to expensive precision-agriculture
services — a smallholder farmer, an agronomy student, an extension worker, an NGO.

**Every recommendation shows its underlying numbers and is framed as a data-grounded estimate, not
certified agronomic advice.** These are simplified models (see each tool's caveats below) meant for
triage and planning, not a substitute for site-specific expertise.

## Tools

| Tool | Description |
|---|---|
| `geocode_location` | Resolve a place name to coordinates (required first step for the others) |
| `get_soil_profile` | Soil texture, pH, organic carbon at multiple depths (SoilGrids) |
| `get_growing_conditions` | Current weather + soil snapshot + short forecast |
| `get_irrigation_advice` | Soil water balance estimate: should you irrigate, and how much? |
| `get_frost_and_heat_risk` | Scans the forecast for frost/freeze and heat-stress risk days |
| `get_growing_degree_days` | GDD accumulation over a date range (crop development/maturity tracking) |
| `get_dry_spell_status` | Consecutive dry days and total precipitation — a rough drought indicator |

## Setup

No API keys needed. Add it to your MCP client and go.

**Claude Code:**

```sh
claude mcp add --transport stdio agrisignal -- npx -y agrisignal-mcp
```

**Claude Desktop** — add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "agrisignal": {
      "command": "npx",
      "args": ["-y", "agrisignal-mcp"]
    }
  }
}
```

Any other MCP client that supports stdio servers can run this the same way: `npx -y agrisignal-mcp`.

## Example usage

- "Should I irrigate my field near Ames, Iowa this week?" → `geocode_location` then `get_irrigation_advice`
- "What's the soil like at this location — good for growing tomatoes?" → `get_soil_profile`
- "Is there a frost risk in the next 10 days?" → `get_frost_and_heat_risk`
- "How many growing degree days have accumulated since I planted on May 15?" → `get_growing_degree_days`
- "Has this region been in a dry spell?" → `get_dry_spell_status`

## Notes on the models used

- **Irrigation advice** is a simplified single-layer soil water balance (in the spirit of FAO-56
  accounting): total available water = (field capacity − wilting point) × root zone depth, projected
  forward using forecast precipitation minus reference evapotranspiration (ET0, not crop-specific
  actual ET). It ignores runoff and drainage below the root zone. Field capacity and wilting point come
  from SoilGrids at 15–30cm depth; current soil moisture from Open-Meteo's 9–27cm band — a reasonable
  but approximate match to a generic root zone, not a specific crop's.
- **Growing degree days** use the modified method common in US extension-service guidance for corn:
  Tmin is floored at the base temperature before averaging, and an optional Tmax cap can be applied.
  Set `floor_tmin_at_base: false` for the plain average method if that fits your crop better.
- **Dry spell severity** thresholds (mild >7 days, moderate >14, severe >21) are a general rule of
  thumb, not a calibrated meteorological drought index (e.g. SPI).
- **SoilGrids no-data pixels**: geocoded place coordinates often land on a town/city center, which can
  be a no-data pixel in SoilGrids' 250m grid (buildings, pavement). Soil-data tools automatically retry
  ~1km away and say so in the response when this happens — for a real field, pass its actual coordinates
  rather than a town center for a more accurate reading.

## Rate limits

Open-Meteo and SoilGrids are free services. Be considerate — avoid hammering either API with rapid
repeated calls; SoilGrids in particular can take several seconds per request.

## Development

```sh
npm install
npm run build
npm test
```

## License

MIT