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

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

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.2
File Size Uploaded Provenance Actions
birdweather_mcp-0.2.2.tar.gz 316.2 kB With provenance Details for birdweather_mcp-0.2.2.tar.gz

Built distribution (wheel)

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

Total release size: 341.2 kB

Release files / birdweather_mcp-0.2.2.tar.gz

Download URL birdweather_mcp-0.2.2.tar.gz
Size 316.2 kB
Tags Source
SHA-256 checksum
How to use checksums
ac3c17131c4611d62e15c7d4adc7127cceb2070dd152c9801e118b48ff9cf81a
BLAKE2b-256 checksum
How to use checksums
52615465b14815b49d31e25adf967f18cd7d883e10a7fe0163bdc37df8f0e153
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.2-py3-none-any.whl

Download URL birdweather_mcp-0.2.2-py3-none-any.whl
Size 25.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
56d6f9bc2108995513722400e530c355b30d7183c6a2267d97ec6d753821e226
BLAKE2b-256 checksum
How to use checksums
efd62e8acd67b4674314586f15c657c8e5cae0d0cc838baaf978bb3d4896d702
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.2

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