birdnet-go-mcp

birdnet-go-mcp is a high-performance Model Context Protocol (MCP) server and CLI tool for BirdNET-Go bioacoustic observation stations. It is designed to connect Claude, Antigravity, OpenClaw, and local large language models to a user's backyard bird monitoring station.

Purpose This tool is used for read-only access to BirdNET-Go observation station data, including querying recent bird detection records, streaming microphone telemetry data, parsing local area network audio recordings, and viewing observation records. It connects directly to BirdNET-Go's v2 REST API, communicating over the local area network or localhost, without locking the raw database and without depending on unmaintained Python dependencies.

Key Capabilities

• Native BirdNET-Go support: interacts directly with the BirdNET-Go v2 REST API, with no raw database locking or unmaintained Python dependencies.
• Instant run: can be started immediately with npx -y birdnet-go-mcp, with no Go toolchain required.
• Zero-dependency static binary: a single Go binary (CGO_ENABLED=0), supporting Linux, macOS, and Windows.
• Dual mode (CLI + MCP): provides a human-oriented CLI for quick terminal health checks (birdnet-mcp status); it also provides a complete stdio and SSE MCP server for AI agents.
• Context protection (8KB envelope): hard-limits output to prevent queries returning hundreds of detections from overflowing the model context window.
• Read-only and parallel-safe: omits all modification/destructive endpoints; all tools are marked with readOnlyHint and idempotentHint, facilitating fast parallel calls.
• Audio and clip access: parses .wav clip URLs from local area network Caddy/Nginx, with built-in base64 audio streaming for multimodal models.

Usage

1. Run instantly via NPX (recommended for Claude Desktop and Node users): no Go installation required; it automatically downloads the native binary for the corresponding platform.
2. Install via Go.
3. Precompiled binaries: download the latest static binary for your ownarchitecture from GitHub Releases, including darwin-arm64 (Apple Silicon M1/M2/M3/M4), darwin-amd64 (Intel Mac), linux-amd64 (x86_64 servers, Proxmox LXC, Docker), linux-arm64 (Raspberry Pi 4 / 5), linux-armv7 (Raspberry Pi 2 / 3 / Zero 2 W).

Client and Runtime Framework Configuration

• Claude Desktop and Cursor: edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows, or add it under Cursor Settings ➔ Features ➔ MCP. It can also be added directly via the CLI.
• Google Antigravity: add it in the Antigravity MCP configuration (~/.gemini/antigravity/mcp/ or project settings).
• OpenClaw: configure it in ~/.openclaw/openclaw.json, and add it to the agent's tools.allow list.
• Remote/headless agents (SSE HTTP mode): if the agent runs on another machine or in the cloud and cannot access local stdio, point the agent to http://<your-server-ip>:8092/sse.

Interactive CLI Commands birdnet-mcp is both a complete human-oriented CLI tool and an MCP server for agents. It can be used to check station and RTSP microphone health, view recent observation records, and download audio recordings.

MCP Tool Reference

• birdnet://station/health: a real-time JSON snapshot of the Pi microphone stream and the BirdNET-Go engine.
• birdnet://detections/recent: the 10 most recent detection records.
• birdnet://species/summary: aggregated summary of species occurrences.
• daily_backyard_brief: a morning briefing workflow template for resident bird agents.
• investigate_detection: an in-depth analysis template for evaluating anomalous observations against eBird.

Production experience and hardening birdnet-go-mcp was not built in a theoretical vacuum, but has been battle-tested and validated in a real backyard bioacoustic observation station:

• Microphone station: Raspberry Pi Zero 2 W installed outdoors, equipped with a weatherproof electret microphone, streaming 48kHz mono audio over Wi-Fi via RTSP (mediamtx) at about 75 KB/s.
• Detector host: BirdNET-Go runs in a Debian 12 Proxmox LXC container (amd64, AMD Ryzen 5 PRO), using the Cornell Lab of Ornithology's neural network to analyze audio chunks.
• Clip web server: Caddy reverse proxy serves the /var/lib/birdnet-go/clips/ directory over HTTP on port 8091.
• Agent grid: OpenClaw runs on an Apple Silicon Mac Mini, running autonomous resident agents: Blenda (infrastructure agent, GLM-5.3) is responsible for monitoring server health, managing gateway restarts, and overseeing tool permissions; Leopold (resident naturalist, Gemini 3.8 Flash) is responsible for writing the daily backyard wildlife briefing, flagging unusual species (Eastern Bluebird, Carolina Wren, Pileated Woodpecker), and checking audio spectrograms.

Real-world experience and "Incident Zero"

• Caddy directory permission trap (Incident Zero): BirdNET-Go creates month-partitioned clip directories (/clips/YYYY/MM/) with permissions 750 (drwxr-x---). External web servers (Caddy, Nginx) running as their own system user encounter HTTP 403 Forbidden when serving audio clips to agents or Discord webhooks. Fix: set the permissions of existing month folders to 755, and add the web server user to the birdnet group: sudo chmod -R 755 /var/lib/birdnet-go/clips and sudo usermod -aG birdnet caddy.
• Apple Silicon AMFI and cross-compilation: when cross-compiling a macOS Go binary from Linux (GOOS=darwin GOARCH=arm64) and stripping debug symbols (-ldflags="-s -w"), macOS Apple Mobile File Integrity (AMFI) immediately terminates the process with SIGKILL (exit code 137). All Darwin ARM64 releases are now correctly ad-hoc code signed (codesign -s - --force).
• Context window token budget protection: feeding raw base64 WAV recordings into a multimodal LLM is very useful for verifying difficult bird calls, but a single 15-second WAV consumes about 1.9MB (about 500,000 tokens), and one tool call can occupy 50% of a 1 million token context window. birdnet-go-mcp strictly limits all structured JSON tool responses to an 8KB envelope cap, while explicitly exempting get_audio_clip_base64, so that the model can deliberately call it without accidentally causing a context explosion during the daily briefing workflow.

Contributing and development, acknowledgements and license Built on mark3labs/mcp-go. Designed for tphakala/birdnet-go. The bird identification neural network was developed by the Cornell Lab of Ornithology and Chemnitz University of Technology. Licensed under the MIT License.