GitHub - zax0rz/birdnet-go-mcp: Model Context Protocol (MCP) server & CLI for BirdNET-Go bioacoustic observatories

Model Context Protocol (MCP) server & CLI for BirdNET-Go bioacoustic observatories - zax0rz/birdnet-go-mcp

Summary

birdnet-go-mcp is a Go-based Model Context Protocol (MCP) server and CLI for BirdNET-Go v2 bioacoustic observatories. It exposes bird detection data, station health telemetry, and audio clip access to MCP-compatible agents like Claude Desktop, Cursor, and OpenClaw over LAN. The project is read-only, parallel-safe, and ships as a static binary or via npx.

What it is useful for

This is for engineers running BirdNET-Go — a Cornell Lab of Ornithology-powered audio detection system — who want AI agents to query sightings, search historical detections, check microphone and detector health, and pull audio clips for verification. It exposes eight MCP tools: get_recent_detections, search_detections, get_detection_detail, get_today_summary, get_new_arrivals, get_station_health, get_audio_clip, and get_audio_clip_base64. The latter streams raw WAV to multimodal models, while structured JSON responses are capped at an 8KB envelope to keep model context from overflowing.

A concrete case from the README's production stack: a Raspberry Pi Zero 2 W streams 48kHz mono audio over RTSP, BirdNET-Go runs in a Proxmox LXC, and an OpenClaw agent on a Mac Mini composes daily wildlife briefings and flags unusual species. Engineers can ask an agent "what birds have I never recorded this season?" or "is the RTSP mic still healthy?" without exposing the BirdNET-Go database directly.

How engineers can use it

The fastest path requires no Go toolchain:

BIRDNET_BASE_URL="http://192.0.2.10:8080" npx -y birdnet-go-mcp status

Or install the Go binary:

go install github.com/zax0rz/birdnet-go-mcp/cmd/birdnet-mcp@latest

Pre-compiled static binaries are published for linux-amd64, linux-arm64, linux-armv7, darwin-arm64, darwin-amd64, and windows-amd64. For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "birdnet": {
      "command": "npx",
      "args": ["-y", "birdnet-go-mcp", "serve"],
      "env": {
        "BIRDNET_BASE_URL": "http://192.0.2.10:8080",
        "CLIPS_BASE_URL": "http://192.0.2.10:8091"
      }
    }
  }
}

For Claude Code: claude mcp add birdnet -- npx -y birdnet-go-mcp serve. For remote agents without stdio access, run birdnet-mcp serve --sse --port 8092 and point the client at http://<server-ip>:8092/sse. Configuration is driven by env vars: BIRDNET_BASE_URL (default http://localhost:8080), CLIPS_BASE_URL (default http://localhost:8091), and optional BIRDNET_USERNAME, BIRDNET_PASSWORD, and BIRDNET_AUTH_TOKEN for protected instances.

The README documents a real gotcha worth flagging: BirdNET-Go creates monthly clip directories with 750 permissions, which causes HTTP 403 when a separate web server (Caddy, Nginx) tries to serve them. The documented fix is chmod -R 755 on the clips root and adding the web server user to the birdnet group. Also note the documented token-budget warning — a single 15-second WAV clip can consume roughly 350,000–500,000 tokens when base64-fed into a multimodal model, so get_audio_clip_base64 is intentionally exempt from the 8KB envelope and should be used selectively.