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

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

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.5
File Size Uploaded Provenance Actions
birdweather_mcp-0.2.5.tar.gz 321.3 kB With provenance Details for birdweather_mcp-0.2.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for birdweather-mcp 0.2.5
File Interpreter ABI Platform Actions
birdweather_mcp-0.2.5-py3-none-any.whl Python 3 none any Details for birdweather_mcp-0.2.5-py3-none-any.whl

Total release size: 348.4 kB

Release files / birdweather_mcp-0.2.5.tar.gz

Download URL birdweather_mcp-0.2.5.tar.gz
Size 321.3 kB
Tags Source
SHA-256 checksum
How to use checksums
1b6a62373364e1e88b29077793ed756215f46c93e16b31df4968d369aefa8fb7
BLAKE2b-256 checksum
How to use checksums
550bb53188ebaedc85a413140b19e8df962dbe6e3a8da2518c5b5c751de03878
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 15, 2026.

Transparency log

Release files / birdweather_mcp-0.2.5-py3-none-any.whl

Download URL birdweather_mcp-0.2.5-py3-none-any.whl
Size 27.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3bd89f83eb4efe4cb99d752ae73fdd206bc93a3e58c55cf6feea77f39eddc1b7
BLAKE2b-256 checksum
How to use checksums
c1c5a9b803b0bf41de06b58a7d324ae47ed4d5df79eda65a474a42d5dda70821
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 15, 2026.

Transparency log

Security for birdweather-mcp 0.2.5

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.5.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 15, 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