Skip to main content
Glama

birdweather-mcp

Self-hostable MCP server for BirdWeather. Point Claude, Cursor, or any MCP client at your (or any public) station and ask natural-language questions about what was detected, what’s trending, and what’s nearby.

Works out of the box against the public GraphQL API — no account required. Optionally set a station token for richer REST fields. The token is never logged or echoed.

Features

  • 15 MCP tools — station info, counts, weather, detections, top species, daily series, species trends, new arrivals, station compare, hourly activity, species search/profiles, nearby stations

  • Prompts & resources — daily/weekly summaries, species deep-dives, and birdweather://station/… URIs

  • No auth required for public GraphQL; optional BIRDWEATHER_STATION_TOKEN for REST

  • stdio (Claude Desktop / Cursor) or streamable-HTTP (Docker / Synology / Tailscale)

  • Token-safe — redacted in logs and errors (SECURITY.md)

  • Docker + compose — prebuilt multi-arch images on GHCR (ghcr.io/pfrederiksen/birdweather-mcp)

Related MCP server: stormscope

Quickstart

uvx (no clone):

uvx birdweather-mcp

pip / pipx:

pip install birdweather-mcp
# or: pipx install birdweather-mcp
birdweather-mcp

Homebrew:

brew install pfrederiksen/tap/birdweather-mcp
birdweather-mcp

Docker (stdio):

docker pull ghcr.io/pfrederiksen/birdweather-mcp:latest
docker run --rm -i ghcr.io/pfrederiksen/birdweather-mcp:latest

Long-lived HTTP on a NAS → Self-hosting. More install paths → Installation. Python / MCP SDK notes → Requirements & compatibility.

Configure Claude Desktop / Cursor / VS Code → Clients.

Documentation

Guide

Description

docs/README.md

Index of all guides

Installation

uvx, pip, pipx, Homebrew, Docker/GHCR, from source

Configuration

Environment variables, station ID/token

Clients

Claude Desktop, Cursor, Claude Code, VS Code, HTTP

Tools

Tools, prompts, and resources

Self-hosting

Docker, Synology/arm64, LAN/Tailscale, updates

Development

Dev setup, tests, lint, release process

Troubleshooting

Common problems and FAQ

Demo

Placeholder illustration of asking an MCP client about Example Station (12345) — not live data.

License

Licensed under MIT. See also CHANGELOG.md, CONTRIBUTING.md, and SECURITY.md.

Available Tools

15 tools
activity_by_hourA

Hourly detection histogram in station-local time (optional species filter).

Time window (station-local; no period parameter): days (default 7) or from_date / to_date as YYYY-MM-DD. There is no hours argument — the result always covers hours 0–23.

Inputs: station_id (required), days, species, to_date, +2 more. Returns: result

compare_stationsB

Compare species lists for two stations over the same window (overlap and uniques).

Time window (station-local; no period parameter): days (default 7) or from_date / to_date as YYYY-MM-DD.

Inputs: station_a (required), station_b (required), days, limit, +3 more. Returns: result

daily_countsB

Per-day detection totals (and optional per-species breakdown) for a station.

Time window (station-local; no period parameter): days (default 7) or from_date / to_date as YYYY-MM-DD.

Inputs: station_id (required), days, species, to_date, +3 more. Returns: result

first_of_yearA

Species whose first detection of the year (or season) falls in the arrival window.

Season bounds use since / until as YYYY-MM-DD in station-local time (not from_date / to_date or period). Default season is Jan 1–today; the arrival window is the last 14 days of that season.

Inputs: station_id (required), year, limit, since, +2 more. Returns: result

get_stationB

Get station metadata: name, location, coords, timezone, detection range, thresholds.

If BIRDWEATHER_STATION_TOKEN is set, also includes all-time REST stats.

Inputs: station_id (required). Returns: result

get_weatherB

Current weather reading for a station, when BirdWeather has one.

Inputs: station_id (required). Returns: result

new_arrivalsB

Alias for first_of_year: new species arrivals in the recent arrival window.

Season bounds use since / until as YYYY-MM-DD (not from_date / to_date or period).

Inputs: station_id (required), year, limit, since, +2 more. Returns: result

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 period parameter): days (default 1) or from_date / to_date as YYYY-MM-DD. Use after with the previous page_info.endCursor for pagination. When BIRDWEATHER_STATION_TOKEN is set, the station REST API is preferred (extra fields like image URLs).

Inputs: station_id (required), days, after, limit, +5 more. Returns: result

search_speciesC

Search BirdWeather's species catalog by common or scientific name fragment.

Inputs: query (required), after, limit. Returns: result

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.

Inputs: lat, lon, after, limit, +2 more. Returns: result

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).

Inputs: query, species_id, scientific_name. Returns: result

species_listA

Alias for top_species: species heard at a station, ranked by count.

Time window (station-local; no period parameter): days (default 7) or from_date / to_date as YYYY-MM-DD.

Inputs: station_id (required), days, limit, offset, +3 more. Returns: result

species_trendB

Counts over time for one species at a station (station-local days or weeks).

Time window (station-local; no period parameter): days (default 30) or from_date / to_date as YYYY-MM-DD. Granularity is day or week.

Inputs: species (required), station_id (required), days, to_date, +3 more. Returns: result

station_countsA

Detection and unique-species counts for a station over a time window.

Time window (station-local calendar days; no period parameter):

  • days (default 7): last N days including today, or

  • from_date / to_date as YYYY-MM-DD in station-local time. Timezone defaults to the station's timezone.

Inputs: station_id (required), days, to_date, timezone, +1 more. Returns: result

top_speciesB

Top species by detection count for a station (alias: species_list).

Time window (station-local; no period parameter): days (default 7) or from_date / to_date as YYYY-MM-DD.

Inputs: station_id (required), days, limit, offset, +3 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 15 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Exposes Weather Underground personal weather station data as tools in Claude, enabling queries for current conditions, daily summaries, hourly history, and station metadata.
      4
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides real-time US weather data for AI assistants via MCP, including current conditions, forecasts, alerts, severe weather outlooks, radar, upper-air analysis, and surface analysis. Supports optional personal weather station integration.
      9
      4
      ISC
    • F
      license
      A
      quality
      C
      maintenance
      Enables LLM clients to query a BirdNET-Go bird-detection instance for detections, species summaries, activity patterns, and historical searches via natural language.
      9
      -