Skip to content

cheekhimself/ecowitt-weather

v0.1.0MIT

Unofficial community plugin that reads current and historical conditions from an EcoWitt weather station (GW3000 and other gateways) via the EcoWitt Cloud API v3, normalized to a StationReading shape. Not affiliated with or endorsed by EcoWitt.

ecowitt-weather (unofficial)

Unofficial community Agent Plugin (with a Cursor Plugin manifest alongside) that exposes the EcoWitt Cloud API v3 (docs) as a zero-dependency stdio MCP server. Tools return a normalized StationReading (or a compact history series derived from it), not raw API JSON.

This project is not affiliated with, endorsed by, or maintained by EcoWitt. EcoWitt is a trademark of its owner. Use it with your own EcoWitt account and station (GW3000 and other gateways that speak the same v3 endpoints).

Tools

  • get_current_reading — GET /device/real_time with call_back=all. Returns a StationReading.
  • get_history — GET /device/history with start_date, end_date, cycle_type, and an explicit channel list (call_back=all is rejected by this endpoint). Returns a compact series.
  • get_device_info — GET /device/info. Returns gateway metadata and, when present, last_reading as a StationReading.

Configuration

The plugin needs three variables. It never stores or ships secret values; you set them in the client (in Cursor: Plugins → Configure). mcp.json only contains ${VAR} placeholders.

VariableWhat it isWhere to get it
ECOWITT_APPLICATION_KEYApplication keySign in at ecowitt.net, then open User Center / account settings → API (also labeled API Management or Private Center → API Keys). Create an Application Key.
ECOWITT_API_KEYUser API keyThe same API Keys page. Create an API Key.
ECOWITT_MACGateway MAC addressThe device dashboard on ecowitt.net, or the Ecowitt / WSView Plus app device list. Format AA:BB:CC:DD:EE:FF.

Never commit a key, MAC, or .env file.

Units

Imperial units are requested by default (temp_unitid=2, pressure_unitid=4 inHg, wind_speed_unitid=9 mph, rainfall_unitid=13 in, solar_irradiance_unitid=16 W/m²). Pass metric: true for °C, hPa, m/s, mm (solar stays W/m²). rainfall_unitid is only 12 (mm) or 13 (in); 14 is rejected.

History timezone

get_history dates are the station's local time (date_zone_id from device/info, for example America/Chicago). Bare YYYY-MM-DD or YYYY-MM-DD HH:MM:SS is sent as-is. ISO-8601 instants are converted into that timezone. Valid cycle_type values are 5min, 30min, 4hour, and auto (240min, 24hour, and 24h return API error 40015). EcoWitt also enforces span limits (for example, 5min requests should stay within one day).

Rate limits

The EcoWitt Cloud API may return code -1 with a message like "Operation too frequent" after a burst of history (or other) calls. Wait a minute or two and retry. Prefer fewer, narrower fields over many overlapping requests.

A GW3000 used as an indoor / tent gateway may have no outdoor, wind, rain, or solar array. In that case those groups are omitted and extra channels (temp_and_humidity_ch*, soil_ch*, temp_ch*, soil_moisture_ec_ch*, battery) carry the useful sensors.

StationReading

{
  time,            // ISO-8601 UTC, latest sensor time when available
  units,           // "imperial" | "metric" (the unit system requested)
  outdoor?:  { temp, humidity, dew_point, feels_like },
  indoor?:   { temp, humidity, dew_point?, feels_like? },
  pressure?: { relative, absolute },
  wind?:     { speed, gust, direction },
  rain?:     { rate, daily, event, source },  // source is rainfall_piezo or rainfall
  solar?:    { radiation, uvi },
  extra?:    { temp_and_humidity_ch1..8, soil_ch1..8, ... }  // only channels the station reported
}

Each measurement is { value, unit }. Missing groups and fields are omitted, never filled in.

Layout

  • plugin.json + mcp.json: Agent Plugins 1.0.0 (portable; uses ${PLUGIN_ROOT}). User secret variables cannot be declared in the root Agent manifest (the 1.0.0 schema does not allow a variables field).
  • .mcp.json: identical copy of mcp.json, so cursor.directory auto-detection (which looks for .mcp.json) finds the MCP server.
  • .cursor-plugin/plugin.json: Cursor manifest. This is where variables are declared (JSON Schema for ECOWITT_APPLICATION_KEY, ECOWITT_API_KEY, and ECOWITT_MAC) and where MCP config uses ${CURSOR_PLUGIN_ROOT} (Cursor does not expand ${PLUGIN_ROOT}).
  • server/index.mjs: MCP server (Node 18+, global fetch, no dependencies).
  • skills/ecowitt-station/SKILL.md: when to call the tools (current conditions, VPD-relevant temp/RH, recent history).
  • LICENSE: MIT, Cheeko / Matthew Cheek.

Local test

node scripts/smoke.mjs

The smoke test validates the manifests, runs initialize / tools/list / tools/call against a mocked v3 fixture (no live keys required), checks the missing-key error, and optionally confirms that the live API returns a clean auth error for obviously fake credentials.