zax0rz/birdnet-go-mcp

A high-performance Model Context Protocol (MCP) server & CLI for BirdNET-Go bioacoustic observatories.
Connect Claude, Antigravity, OpenClaw, and local LLMs to your backyard bird monitoring station.
---
Highlights
- **Native BirdNET-Go Support**: Interfaces directly with BirdNET-Go's v2 REST API over LAN or localhost. No raw database locking or unmaintained Python dependencies.
- **Instant npx Run**: Launch immediately with npx -y birdnet-go-mcp — zero Go toolchain required.
- **Zero-Dependency Static Binary**: Single Go binary (CGO_ENABLED=0) compiled for Linux, macOS, and Windows.
- **Dual-Mode (CLI + MCP)**: Human-friendly CLI for quick terminal health checks (birdnet-mcp status), plus full stdio & SSE MCP server for AI agents.
- **Context-Protected (8KB Envelope)**: Hard-capped output preventing multi-hundred detection queries from overflowing model context windows.
- **Read-Only & Parallel-Safe**: Omits all mutating/destructive endpoints. Annotates all tools with readOnlyHint and idempotentHint for fast parallel agent calls.
- **Audio & Clip Access**: Resolves LAN Caddy/Nginx .wav clip URLs, with built-in base64 audio streaming for multimodal models.
---
Quick Start
1. Instant Run via NPX (Recommended for Claude Desktop & Node users)
No Go installation needed. Downloads the native binary for your platform automatically:
2. Install via Go
3. Pre-Compiled Binaries
Download the latest static binary for your architecture from GitHub Releases:
- 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)
- windows-amd64
---
Client & Harness Setup
Claude Desktop & Cursor
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows), or add under Cursor Settings ➔ Features ➔ MCP:
Option A: Using npx (Easiest)
Option B: Using Native Binary
---
Claude Code
Add directly via CLI:
---
Google Antigravity
In your Antigravity MCP configuration (~/.gemini/antigravity/mcp/ or project settings):
---
OpenClaw
In ~/.openclaw/openclaw.json:
In your agent's tools.allow list:
---
Remote / Headless Agents (SSE HTTP Mode)
If your agent runs on another machine or in the cloud without access to local stdio:
Point your agent to:
http:// :8092/sse
---
Interactive CLI Commands
birdnet-mcp is a full CLI tool for humans as well as an MCP server for agents.
Check Station & RTSP Mic Health
View Recent Sightings
Download Audio Recording
---
MCP Tool Reference
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| get_recent_detections | limit (int, 1-25) min_confidence (0.0-1.0) species_code (string) | Fetches the most recent bird acoustic detections with confidence scores, timestamps, and audio clip URLs. |
| search_detections | date (YYYY-MM-DD) species (name/code) min_confidence (0.0-1.0) limit (int) | Historical search through detection records stored in SQLite. |
| get_detection_detail | id (int, required) | Inspects a single detection: weather conditions at detection time, confidence breakdown, and audio clip info. |
| get_today_summary | *(none)* | Aggregate summary of today's observatory run: total count, species diversity, and top visitors. |
| get_new_arrivals | *(none)* | Identifies species heard for the first time ever or new this season/year (vital for tracking migration). |
| get_station_health | *(none)* | Real-time diagnostic telemetry: RTSP mic stream state, ingest bit rate, dropped packets, and host uptime. |