birdweather-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@birdweather-mcp What species were detected at my station in the last 3 days?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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/…URIsNo auth required for public GraphQL; optional
BIRDWEATHER_STATION_TOKENfor RESTstdio (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-mcppip / pipx:
pip install birdweather-mcp
# or: pipx install birdweather-mcp
birdweather-mcpHomebrew:
brew install pfrederiksen/tap/birdweather-mcp
birdweather-mcpDocker (stdio):
docker pull ghcr.io/pfrederiksen/birdweather-mcp:latest
docker run --rm -i ghcr.io/pfrederiksen/birdweather-mcp:latestLong-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 |
Index of all guides | |
uvx, pip, pipx, Homebrew, Docker/GHCR, from source | |
Environment variables, station ID/token | |
Claude Desktop, Cursor, Claude Code, VS Code, HTTP | |
Tools, prompts, and resources | |
Docker, Synology/arm64, LAN/Tailscale, updates | |
Dev setup, tests, lint, release process | |
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 toolsactivity_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, orfrom_date/to_dateas 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
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.
Maintenance
Related MCP Connectors
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. To get started, including information on signing up and obtaining your Ambee key, check out the Ambee documentation on https://docs.ambeedata.com
Hosted MCP server from TwitterAPI.io that gives AI agents read-only access to Twitter/X data. 12 tools: tweet search with X operators, user profiles, a user's latest tweets, followers and followings, replies, quotes, retweeters, mentions and trends. Connect at https://mcp.twitterapi.io/mcp with a TwitterAPI.io API key or account sign-in; usage is paid per result returned.
Weather, code search, currency & Solana trust scoring as MCP tools. Free, no API key needed.
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Related MCP Servers
- AlicenseAqualityDmaintenanceExposes Weather Underground personal weather station data as tools in Claude, enabling queries for current conditions, daily summaries, hourly history, and station metadata.4MIT
- AlicenseAqualityBmaintenanceProvides 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.94ISC
- FlicenseNot gradedqualityDmaintenanceProvides tools for weather, GitHub issues, and Slack messaging to MCP-compatible AI assistants.-
- FlicenseAqualityCmaintenanceEnables LLM clients to query a BirdNET-Go bird-detection instance for detections, species summaries, activity patterns, and historical searches via natural language.9-