ambeelabs/ambee-mcp

The official Model Context Protocol server for Ambee. It gives any MCP-compatible AI assistant — Claude, ChatGPT, Cursor, VS Code, Ollama, and more — direct access to live **air quality**, **pollen**, and **weather** data.
Point your assistant at this server and it can answer questions like *"Is it a bad tree pollen day in Atlanta?"* or *"Should we move the Saturday offsite indoors?"* by calling Ambee's data directly, instead of guessing from stale training data.
Looking for a ready to access server? Try our host Ambee MCP
Table of contents
- Tools
- Error handling
- Requirements
- Install
- Configure
- Run standalone
- Connect a client
- Example prompts
- Support
- Contributing
- License
Tools
Six tools — latest conditions and a 48-hour forecast for each of the three datasets:
| Tool | Endpoint | Returns |
| --- | --- | --- |
| air_quality_latest | GET /v3/aq/latest | AQI + CO/NO2/O3/PM10/PM2.5/SO2, dominant pollutant, category. 1 record. |
| air_quality_forecast | GET /v3/aq/forecast/48hrs | Same fields, hourly. Up to 48 records. |
| weather_latest | GET /v3/weather/latest | Temperature, apparent temp, humidity, dew point, pressure, cloud cover, precipitation, wind, UV index, ozone, visibility, summary. 1 record. |
| weather_forecast | GET /v3/weather/forecast/48hrs | Same fields, hourly. Up to 48 records. |
| pollen_latest | GET /v3/pollen/latest | Tree/grass/weed counts + risk levels, optional per-species breakdown. 1 record. |
| pollen_forecast | GET /v3/pollen/forecast/48hrs | Same fields, hourly. Up to 48 records. |
Every tool accepts **either**:
- lat + lng (numbers), **or**
- place (free text, e.g. "Bengaluru")
Sending both, or neither, is rejected client-side before any request is made. All /v3 endpoints accept place natively, so no separate geocoding step is needed.
Optional parameters:
- locale (boolean) — adds a localTime field to each record.
- aqiStandard (air quality only) — EPA (default), IN, UK, CN, or CA.
- units (weather only) — imperial (default), metric, or si.
- speciesRisk (pollen only) — include per-species risk levels where the region supports it.
Error handling
Every response is checked against Ambee's documented status codes:
| Code | Meaning | How this server handles it |
| --- | --- | --- |
| 200 | OK | Returned as normal tool output. |
| 206 | Partial data (quota ran out mid-response) | Returned as usable data, with a warning field explaining it's trimmed. |
| 400 | Bad request | Returned as a tool error explaining likely cause (missing/invalid params). |
| 401 | Unauthorized | Returned as a tool error — check AMBEE_API_KEY. |
| 403 | Forbidden | Returned as a tool error — key lacks permission for this endpoint. |
| 404 | Not found | Returned as a tool error — no data for that location. |
| 422 | Quota exceeded | Returned as a tool error — plan quota hit. |
| 429 | Rate limited | Returned as a tool error — back off and retry. |
| 500 | Internal server error | Returned as a tool error — retry later. |
| 299 | Deprecated | Returned as a tool error — endpoint/feature not supported. |
Every non-2xx response comes back as an MCP tool error (isError: true) with a human-readable message combining Ambee's own error text and a short hint on what to do next, so the calling assistant can explain the failure instead of just surfacing a raw status code.