AI导哈

鸟类检测数据分析服务器

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

  • by DMontgomery40
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 DMontgomery40/mcp-local-server

使用说明

mcp BirdNET Pi服务器

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

特性

  • 基于日期和物种过滤的鸟类检测数据检索
  • 检测统计分析
  • 录音访问（base64或缓冲区）
  • 按小时细分的日常活动模式
  • HTML和JSON报告生成
  • 双重传输：stdio（默认）和可流式传输http

需求

  • Python 3.10+
  • MCP Python SDK>=1.26.0

安装

pip install -r requirements.txt

或者使用紫外线：

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

流式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 build -t mcp-birdnet-pi-server .
docker run -p 8000:8000 -v /path/to/data:/app/data mcp-birdnet-pi-server

克劳德桌面版

添加 ~/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

许可证

麻省理工学院

附录：MCP实践（代码执行、工具规模和安全）

最后更新时间：2026-03-23

为何存在此附录

模型上下文协议（MCP）仍然是工具和代理最有用的互操作层之一。权衡的是，大型MCP服务器可能会暴露许多工具，而简单的工具调用可能会用模式、工具聊天和无关的调用痕迹淹没上下文窗口。

在实践中，“更多的工具”并不总是“更好的结果”。工具表面积必须与执行模式相匹配，以保持令牌使用的限制和行为的可预测性。

转换到代码执行/代码模式

最近的工作流程越来越多地将复杂的编排从聊天环境转移到代码执行循环中。这减少了重复的模式标记，使工具使用可审计和可测试。

核心阅读：

客户适合指南（简短版）

  • 克劳德代码/代码/光标：适用于直接MCP工作流程，但仍受益于狭窄的工具表面。
  • 代码执行包装器（TypeScript/Python CLI）：当工具数量较多或任务链包含多个步骤时更好。
  • MCP控制较弱的托管聊天客户端：通过预包装的CLI或网关工具通常更安全。

快速注射：风险、影响和缓解措施

对于使用工具的代理来说，快速注入仍然是一个悬而未决的安全问题。它是可控的，但不是“解决”的

主要风险：

  • 隐藏在工具输出或远程内容中的恶意指令。
  • 秘密渗透和未经授权的外部通话。
  • 不安全的状态更改（破坏性文件/系统/API操作）。

缓解基线：

  • 凭据和工具范围的最低权限。
  • 列出目的地并实施出口控制。
  • 严格的输入验证和模式执行。
  • 人为确认破坏性/高风险行为。
  • 具有资源/时间限制的沙盒执行。
  • 结构化日志记录、审计跟踪和可回放运行。
  • 模型重新摄取前的输出过滤/编辑。

除非明确验证，否则将每个工具输出视为不受信任的输入。

相关 MCP