BirdNet-Pi MCP Server

mcp-BirdNET-Pi-server

BirdNET-Pi と連携する Model Context Protocol（MCP）サーバーです。ローカルの BirdNET-Pi インストール環境から、鳥の検出データ、統計情報、音声録音、活動パターン、レポートを取得するツールを提供します。

機能

• 日付や種で絞り込んだ鳥の検出データの取得
• 検出統計と分析
• 音声録音へのアクセス（base64 または buffer）
• 時間ごとの内訳を含む、日単位の活動パターン
• HTML および JSON レポートの生成
• 2 種類のトランスポート：stdio（デフォルト）および streamable-http

要件

• Python 3.10+
• MCP Python SDK >= 1.26.0

インストール

pip install -r requirements.txt

または、uv を使用します：

uv pip install -r requirements.txt

設定

環境変数：

• BIRDNET_DETECTIONS_FILE：検出データ JSON ファイルのパス（デフォルト：data/detections.json）
• BIRDNET_AUDIO_DIR：音声ファイルディレクトリのパス（デフォルト：data/audio）
• BIRDNET_REPORT_DIR：レポートディレクトリのパス（デフォルト：data/reports）

サーバーの起動

stdio（デフォルト）

python server.py

Streamable HTTP

MCP_TRANSPORT=http python server.py

または、カスタムのホスト／ポートを指定します：

MCP_TRANSPORT=http MCP_HTTP_HOST=0.0.0.0 MCP_HTTP_PORT=8000 python server.py

Docker

docker build -t mcp-birdnet-pi-server .
docker run -p 8000:8000 -v /path/to/data:/app/data mcp-birdnet-pi-server

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "birdnet": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-BirdNET-Pi-server/server.py"]
    }
  }
}

利用可能なツール

get_detections

日付範囲と任意の種で絞り込んだ鳥の検出データを取得します。

• start_date（必須）：YYYY-MM-DD 形式の開始日
• end_date（必須）：YYYY-MM-DD 形式の終了日
• species（任意）：種名による絞り込み（部分一致、大文字と小文字を区別しません）

get_stats

期間の検出統計を集計して取得します。

• period（必須）：day、week、month、または all
• min_confidence（任意）：信頼度の最小しきい値 0.0-1.0（デフォルト：0.0）

get_audio

特定の鳥の検出に対応する音声録音を取得します。

• filename（必須）：検出レコードに記載されている音声ファイル名
• format（任意）：base64（デフォルト）または buffer

get_activity

特定の日の、時間ごとの鳥の活動パターンを取得します。

• date（必須）：YYYY-MM-DD 形式の日付
• species（任意）：種名による絞り込み

generate_report

日付範囲を指定して検出レポートを生成します。

• start_date（必須）：レポートの開始日
• end_date（必須）：レポートの終了日
• format（任意）：json（デフォルト）または html

テスト

python -m pytest test_server.py -v

ディレクトリ構成

mcp-BirdNET-Pi-server/
├── birdnet/
│   ├── __init__.py
│   ├── config.py
│   ├── functions.py
│   └── utils.py
├── data/
│   └── detections.json
├── server.py
├── test_server.py
├── Dockerfile
├── requirements.txt
└── README.md

ライセンス

MIT

---

付録：実践における MCP（コード実行、ツール規模、安全性）

最終更新日：2026-03-23

この付録の目的

Model Context Protocol（MCP）は、ツールやエージェントのための、今なお非常に有用な相互運用レイヤーの 1 つです。一方で、大規模な MCP サーバーは多くのツールを公開できるため、単純なツール呼び出しでは、スキーマ、ツールのやり取り、関連性のない呼び出し履歴でコンテキストウィンドウがあふれることがあります。

実際には、「ツールが多い」ことが常に「より良い成果」につながるとは限りません。トークン使用量を抑え、動作を予測可能に保つ実行パターンと、ツールの範囲を組み合わせる必要があります。

コード実行／コードモードへの移行

近年のワークフローでは、複雑なオーケストレーションをチャットのコンテキストからコード実行ループへ移す傾向が強まっています。これにより、繰り返し発生するスキーマのトークンを減らし、ツールの使用状況を監査・テストしやすくなります。

参考資料：

• Cloudflare：コードモード
• Cloudflare：MCP によるコード実行
• Anthropic：MCP によるコード実行

クライアントの適合性ガイド（概要）

• Claude Code / Codex / Cursor：MCP を直接使うワークフローに適していますが、ツールの範囲を絞るとさらに効果的です。
• コード実行ラッパー（TypeScript/Python CLI）：ツール数が多い場合や、タスクの連鎖が複数ステップにわたる場合に適しています。
• MCP の制御機能が弱いホスト型チャットクライアント：事前にラップした CLI やゲートウェイツールを介するほうが安全な場合が多いです。

プロンプトインジェクション：リスク、影響、緩和策

ツールを使用するエージェントにとって、プロンプトインジェクションは依然として未解決のセキュリティ問題です。対処は可能ですが、「解決済み」ではありません。

主なリスク：

• ツールの出力やリモートコンテンツに隠された悪意のある指示。
• シークレットの窃取や、許可されていない外部呼び出し。
• 危険な状態変更（破壊的なファイル／システム／API 操作）。

基本的な緩和策：

• 認証情報とツールのスコープに最小権限を適用する。
• 宛先を許可リストに登録し、送信トラフィックを制御する。
• 厳格な入力検証とスキーマの適用。
• 破壊的／高リスクな操作には人間の確認を求める。
• リソース／時間の制限を設けたサンドボックス環境で実行する。
• 構造化ログ、監査証跡、再現可能な実行を確保する。
• モデルに再入力する前に、出力をフィルタリング／秘匿化する。

明示的に検証されていない限り、すべてのツール出力を信頼できない入力として扱ってください。