BirdNet-Pi MCP Server

A Python-based Model Context Protocol (MCP) server for BirdNet-Pi integration.

Features

• Bird detection data retrieval with date and species filtering
• Detection statistics and analysis
• Audio recording access
• Daily activity patterns
• Report generation

Requirements

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

Installation

1. Clone the repository:

git clone https://github.com/YourUsername/mcp-server.git
cd mcp-server

1. Create a virtual environment and activate it:

python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate

1. Install dependencies:

pip install -r requirements.txt

1. Set up your data directories:

mkdir -p data/audio data/reports

Configuration

The server can be configured using environment variables: - BIRDNET_DETECTIONS_FILE: Path to detections JSON file (default: 'data/detections.json') - BIRDNET_AUDIO_DIR: Path to audio files directory (default: 'data/audio') - BIRDNET_REPORT_DIR: Path to reports directory (default: 'data/reports')

Running the Server

Start the server:

python server.py

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

API Endpoints

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

Available Functions

1. getBirdDetections
2. Get bird detections filtered by date range and species

3. Parameters: startDate, endDate, species (optional)

4. getDetectionStats

5. Get detection statistics for a time period

6. Parameters: period ('day', 'week', 'month', 'all'), minConfidence (optional)

7. getAudioRecording

8. Get audio recording for a detection

9. Parameters: filename, format ('base64' or 'buffer')

10. getDailyActivity

11. Get bird activity patterns for a specific day

12. Parameters: date, species (optional)

13. generateDetectionReport

14. Generate a report of detections
15. Parameters: startDate, endDate, format ('html' or 'json')

Directory Structure

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