mcp-local

This MCP server provides a Python-based BirdNet-Pi integration that exposes BirdNet detections, statistics, audio access, daily activity patterns, and report generation through the MCP interface. It runs a FastAPI application under server.py and exposes endpoints such as /functions to list available capabilities and /invoke to call specific functions. You can filter detections by date and species, retrieve detection statistics for a chosen period, fetch audio recordings for detections, view daily bird activity, and generate reports in HTML or JSON formats. Configure the server via environment variables to point to your detections data, audio files, and reports output, then start the server and use the MCP client to query the functions you need.

Prerequisites:

• Python 3.8 or newer
• Virtual environment support (optional but recommended)
• Internet access to install dependencies from requirements.txt

Step-by-step 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: venv\Scripts\activate

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

4. Prepare data directories (optional but recommended): mkdir -p data/audio data/reports

5. Configure environment variables (see mcp_config):

   • Set BIRDNET_DETECTIONS_FILE to the path of detections JSON
   • Set BIRDNET_AUDIO_DIR to the path of audio files
   • Set BIRDNET_REPORT_DIR to the path for generated reports

6. Run the server: python server.py

7. Access the API at http://localhost:8000

Notes:

• If your data locations differ, update the BIRDNET_* environment variables before starting the server.
• Ensure the detections JSON format is compatible with BirdNet-Pi expectations as used by the server.
• The server exposes functions via /functions and accepts /invoke payloads to call specific endpoints.
• If the server cannot start, check that the required dependencies in requirements.txt are installed and that the ports are not in use.
• For production, consider running behind a reverse proxy and enabling proper authentication if exposed publicly.