
birdweather-mcp
io.github.pfrederiksen/birdweather-mcp
MCP server for BirdWeather station detections, species, and stats.
Documentation
Ask your AI about the birds your station is hearing — detections, species, and stats via MCP.
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_TOKENfor 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)
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.
birdweather-mcppip install birdweather-mcpghcr.io/pfrederiksen/birdweather-mcp:0.2.5docker pull ghcr.io/pfrederiksen/birdweather-mcp:0.2.5:undefined