Skip to main content

birdweather-mcp

Ask your AI about the birds your station is hearing — detections, species, and stats via MCP.

MIT License Python 3.11+ PyPI MCP compatible Docker ready

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)

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

Demo conversation about Example Station 12345

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)

Source distribution for birdweather-mcp 0.2.3
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)

Table of built distributions (wheels) for birdweather-mcp 0.2.3
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page