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.
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.
Metadata
Release files for birdweather-mcp 0.2.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| birdweather_mcp-0.2.3.tar.gz | 317.0 kB | With provenance | Details for birdweather_mcp-0.2.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| birdweather_mcp-0.2.3-py3-none-any.whl | Python 3 | none | any | Details for birdweather_mcp-0.2.3-py3-none-any.whl |
Total release size: 342.4 kB
Release files / birdweather_mcp-0.2.3.tar.gz
| Download URL | birdweather_mcp-0.2.3.tar.gz |
|---|---|
| Size | 317.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
af7edbbf4a755f5ccbfe4a1999270e696eacfde7bc10dd0fc70ee9b3b5c8fc07
|
|
BLAKE2b-256 checksum How to use checksums |
af8eccad5e20cfa742027e0b441ff7f2e149afa8d9fadb2895ce9a515d996d14
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logRelease files / birdweather_mcp-0.2.3-py3-none-any.whl
| Download URL | birdweather_mcp-0.2.3-py3-none-any.whl |
|---|---|
| Size | 25.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4606fd09678b65fa017f4dd3515344d2923769f65ce982005d3f79f7ce7bffaa
|
|
BLAKE2b-256 checksum How to use checksums |
e5599f31ed273530c99afe1158a3e14fbe77d874fe9039bab69635f3ba8ff678
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logSecurity for birdweather-mcp 0.2.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for birdweather_mcp-0.2.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.