BirdNet-Pi

You run a BirdNet-Pi MCP Server to access bird detections, statistics, audio, and reports via a standardized MCP interface. This server exposes functions you can call from an MCP client to filter detections by date or species, retrieve statistics, fetch audio, review daily activity, and generate reports, all powered by BirdNet-Pi data.

How to use

You connect to the BirdNet-Pi MCP Server from your MCP client and call the available functions to access detections, stats, audio recordings, daily activity, and reports. Use date ranges, species filters, and formatting options to tailor results. Start by requesting detections within a specific period and then drill down into statistics or audio files as needed. When you need a local audio file, you can request the recording by its filename and preferred format.

How to install

# Prerequisites
- Python 3.8+
- Internet access for package installation (or a mirror)

# 1. Clone the repository and navigate into the project folder
git clone https://github.com/YourUsername/mcp-server.git
cd mcp-server

# 2. Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Set up data directories for audio and reports
mkdir -p data/audio data/reports

# 5. Run the server
python server.py

# 6. Access the MCP API
# The server will be available at http://localhost:8000

Configuration and usage notes

You can configure paths for detections, audio, and reports using environment variables. If present, the following variables point to respective locations: BIRDNET_DETECTIONS_FILE (default: data/detections.json), BIRDNET_AUDIO_DIR (default: data/audio), and BIRDNET_REPORT_DIR (default: data/reports). If you customize locations, ensure your MCP client can reach the updated paths.

Server endpoints and behavior

The server exposes an HTTP API with endpoints for function discovery and invocation:

• /functions: lists available functions
• /invoke: executes a selected function with provided parameters You run the server locally using the standard Python command and then interact with the endpoints to retrieve detections, stats, audio, daily activity, and reports.

Example usage patterns

• Retrieve detections for a date range and optional species
• Get detection statistics for a chosen period (day, week, month, all)
• Fetch an audio recording by filename in base64 or raw buffer form
• Get daily activity for a specific day and optional species
• Generate a detection report in HTML or JSON format

Troubleshooting tips

If the server fails to start, ensure you are using Python 3.8 or newer, that all dependencies installed correctly, and that the data directories exist with proper permissions. If you cannot reach http://localhost:8000, check that the server process is running and that there are no port conflicts.

Notes on security and deployment

Run the MCP server in a controlled environment if you expose it over a network. Consider wiring in authentication or IP filtering at the application layer if you plan to serve multiple clients. For local development, keep the default localhost binding to minimize exposure.

Appendix: Tools and endpoints

# No code here; this section lists available functions and their purposes in plain language.

Available tools

getBirdDetections

Fetch bird detections filtered by date range and optional species to build analyses or reports.

getDetectionStats

Retrieve detection statistics for a given period such as day, week, month, or all, with optional minimum confidence.

getAudioRecording

Obtain the audio recording for a specific detection by filename in either base64 or binary buffer form.

getDailyActivity

Analyze daily bird activity patterns for a specific date with optional species filter.

generateDetectionReport

Create a report of detections in HTML or JSON format for a given date range.