birdweather-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MCP_HOST | No | Bind host for HTTP transports. | 127.0.0.1 |
| MCP_PORT | No | Bind port for HTTP transports. | 8000 |
| MCP_TRANSPORT | No | Transport to use: stdio (default), streamable-http, or sse. | stdio |
| MCP_ALLOWED_HOSTS | No | Comma-separated Host headers for HTTP, e.g. nas.example.local:* . Unset means loopback only. Use * to allow any host on trusted networks. Fixes 421 Invalid Host header for MagicDNS/LAN names. | |
| BIRDWEATHER_STATION_TOKEN | No | Station API token. Enables REST detections/stats. Never logged. Without it, public GraphQL only. Optional. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Query BirdWeather stations: detections, top species, daily counts, species trends, new arrivals, station comparison, hourly activity, species info, and nearby stations. Public GraphQL needs no auth. Set BIRDWEATHER_STATION_TOKEN for richer station REST data. Use IANA timezones (e.g. America/Los_Angeles). Station IDs are numeric (see app.birdweather.com/stations/). Unknown tool arguments are rejected; use days or from_date/to_date for time windows (there is no period parameter).
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_stationB | Get station metadata: name, location, coords, timezone, detection range, thresholds. If BIRDWEATHER_STATION_TOKEN is set, also includes all-time REST stats. |
| station_countsA | Detection and unique-species counts for a station over a time window. Time window (station-local calendar days; no
|
| get_weatherB | Current weather reading for a station, when BirdWeather has one. |
| recent_detectionsA | List recent detections for a station. Filters: optional species (id, common name, or scientific name), min_confidence (0–1).
Time window (station-local; no |
| top_speciesB | Top species by detection count for a station (alias: species_list). Time window (station-local; no |
| species_listA | Alias for top_species: species heard at a station, ranked by count. Time window (station-local; no |
| daily_countsB | Per-day detection totals (and optional per-species breakdown) for a station. Time window (station-local; no |
| species_infoB | Species profile: names, eBird/Wikipedia links, images, summary. Look up by species_id, scientific_name, or a free-text query (common or scientific name). |
| search_speciesC | Search BirdWeather's species catalog by common or scientific name fragment. |
| search_stationsB | Find stations near a lat/lon (default 25 km radius) and/or by name query. Geographic results include distance_km from the search point, sorted nearest-first. |
| species_trendB | Counts over time for one species at a station (station-local days or weeks). Time window (station-local; no |
| first_of_yearA | Species whose first detection of the year (or season) falls in the arrival window. Season bounds use |
| new_arrivalsB | Alias for first_of_year: new species arrivals in the recent arrival window. Season bounds use |
| compare_stationsB | Compare species lists for two stations over the same window (overlap and uniques). Time window (station-local; no |
| activity_by_hourA | Hourly detection histogram in station-local time (optional species filter). Time window (station-local; no |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| daily_station_summary | Prompt: summarize today's activity at a station. |
| weekly_report | Prompt: weekly detection report for a station. |
| species_deep_dive | Prompt: deep-dive one species at a station. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 15 tools
The tools target clearly different questions (station metadata, counts, weather, detections, trends, comparisons), and descriptions spell out the distinctions well. The main issue is the intentional alias pairs (species_list = top_species, new_arrivals = first_of_year), which present duplicate capabilities an agent may still deliberate over or double-call.
All names are snake_case and readable, with a mostly noun-phrase convention plus a few verb-prefixed lookups (get_station, get_weather, search_species, search_stations). It is not a single strict verb_noun pattern, but the deviations are minor and predictable.
15 tools is a reasonable scope for a station-detection analytics server, covering stats, trends, search, and comparison without sprawling. However, two of the 15 are pure aliases, which slightly inflates the surface.
The set covers station metadata, weather, detections with pagination, species lookup/search, per-day and per-hour counts, trends, arrivals, and cross-station comparison — a deep lifecycle for the domain. Minor gaps: no single-detection detail lookup and no station-management or account-level operations.