MCP Local Server

🚀 BirdNET Pi MCP Server

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

🚀 Quick Start

This is a Python-based Model Context Protocol (MCP) server designed for BirdNET Pi integration. It allows you to filter and retrieve bird detection data, perform statistical analysis, access audio recordings, and generate reports.

✨ Features

• Filter and retrieve bird detection data by date and species.
• Conduct detection statistics and analysis.
• Access audio recordings.
• Analyze daily activity patterns.
• Generate reports.

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

pip install -r requirements.txt

4. Set up your data directory:

mkdir -p data/audio data/reports

📚 Documentation

Configuration

The server can be configured via environment variables:

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

Running the Server

Start the server:

python server.py

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

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

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

3. getAudioRecording

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

4. getDailyActivity

   • Retrieve 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')

🔧 Technical Details

Directory Structure

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

Requirements

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