BirdNet-Pi MCP Server

mcp-BirdNET-Pi-server

用于集成 BirdNET-Pi 的模型上下文协议（MCP）服务。提供工具，用于从本地 BirdNET-Pi 安装中查询鸟类检测数据、统计信息、音频录音、活动模式和报告。

功能

• 按日期和物种筛选并获取鸟类检测数据
• 检测统计与分析
• 访问音频录音（base64 或缓冲区）
• 每日活动模式，按小时细分
• 生成 HTML 和 JSON 报告
• 双传输方式：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

本附录的目的

模型上下文协议（MCP）仍然是工具和 Agent 最实用的互操作层之一。需要权衡的是，大型 MCP 服务可能会暴露许多工具，而简单粗放的工具调用会让上下文窗口充斥工具架构、工具调用对话和无关的调用轨迹。

在实践中，“更多工具”并不总能带来“更好的结果”。工具范围必须配合相应的执行模式，才能控制令牌用量并确保行为可预测。

转向代码执行 / Code Mode

近期的工作流越来越多地将复杂编排从聊天上下文移到代码执行循环中。这能减少重复的架构令牌，并使工具使用过程可审计、可测试。

核心阅读：

• Cloudflare：Code Mode
• Cloudflare：通过 MCP 执行代码
• Anthropic：通过 MCP 执行代码

客户端适配指南（简版）

• Claude Code / Codex / Cursor：适合直接使用 MCP 工作流，但仍可从缩小工具范围中受益。
• 代码执行封装器（TypeScript/Python CLI）：工具数量较多或任务链包含多个步骤时更合适。
• MCP 控制能力较弱的托管聊天客户端：通常通过预封装的 CLI 或网关工具使用更安全。

提示词注入：风险、影响与缓解措施

提示词注入仍是使用工具的 Agent 面临的开放式安全问题。这个问题可以管理，但尚未“解决”。

主要风险：

• 隐藏在工具输出或远程内容中的恶意指令。
• 秘密数据外泄和未经授权的外部调用。
• 不安全的状态变更（破坏性文件／系统／API 操作）。

基线缓解措施：

• 凭据和工具权限范围遵循最小权限原则。
• 将目标地址加入允许列表，并实施出口流量管控。
• 严格验证输入并强制执行架构约束。
• 对破坏性／高风险操作进行人工确认。
• 在沙箱中执行，并限制资源和时间。
• 采用结构化日志、审计跟踪和可重放运行记录。
• 在将输出重新输入模型前进行过滤／脱敏。

除非经过明确验证，否则应将所有工具输出视为不可信输入。