Birdnet Pi

🚀 BirdNet Pi MCP Server

A Python-based Model Context Protocol (MCP) server for BirdNet Pi integration, which can efficiently manage and analyze bird detection data.

🚀 Quick Start

The BirdNet Pi MCP Server is a Python-based application designed for BirdNet Pi integration. Here's how to get it up and running:

Installation

1. Clone the repository:

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 the dependencies:

pip install -r requirements.txt

4. Set up the data directories:

mkdir -p data/audio data/reports

Configuration

The server can be configured using environment variables:

• BIRDNET_DETECTIONS_FILE: Path to the detections JSON file (default: 'data/detections.json')
• BIRDNET_AUDIO_DIR: Path to the audio files directory (default: 'data/audio')
• BIRDNET_REPORT_DIR: Path to the reports directory (default: 'data/reports')

Running the Server

Start the server:

python server.py

The server will run at http://localhost:8000.

✨ Features

• Retrieve bird detection data filtered by date and species.
• Obtain detection statistics and conduct analysis.
• Access audio recordings.
• Get daily activity patterns.
• Generate reports.

📦 Installation

Prerequisites

• Python 3.8+
• FastAPI
• Uvicorn
• Other dependencies listed in requirements.txt

Steps

The installation steps are detailed in the "Quick Start" section above.

💻 Usage Examples

API Endpoints

• /functions - List available functions (GET)
• /invoke - Invoke a function (POST)

Available Functions

1. getBirdDetections

   • Retrieve bird detection data filtered by date range and species.
   • Parameters: startDate, endDate, species (optional)

2. getDetectionStats

   • Obtain detection statistics for a given period.
   • Parameters: period ('day', 'week', 'month', 'all'), minConfidence (optional)

3. getAudioRecording

   • Get the audio recording of a detection.
   • Parameters: filename, format ('base64' or 'buffer')

4. getDailyActivity

   • Get the bird activity pattern for a specific date.
   • Parameters: date, species (optional)

5. generateDetectionReport

   • Generate a detection report.
   • Parameters: startDate, endDate, format ('html' or 'json')

📚 Documentation

Directory Structure

mcp-server/
├── birdnet/
│   ├── __init__.py
│   ├── config.py
│   ├── functions.py
│   └── utils.py
├── data/
│   ├── audio/
│   └── reports/
├── server.py
├── requirements.txt
└── README.md

This structure organizes the project's source code, data storage, and configuration files effectively.