foxglove_mcp_server

guangzhou/foxglove_mcp_server

3.2

If you are the rightful owner of foxglove_mcp_server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Foxglove MCP Server is a robust server implementation designed to facilitate communication and data exchange using the Model Context Protocol (MCP).

Foxglove MCP Server – Local / Cloud / Annotation

把 Foxglove 能力（本地 MCAP 解析、可选 Data Platform、实时 WebSocket、时序抽取与高亮、图片/视频标注）通过 MCP 暴露给大模型 / IDE 代理（Cline、Cursor 等）。

目录结构

.
├─ foxglove_mcp_server_local.py            # 纯本地版（MCAP + 时序/高亮 + 视频预览 + 报告 + WebSocket）
├─ foxglove_mcp_server_local_annot.py      # 本地版（含 OpenCV 图片/视频标注工具）
├─ foxglove_mcp_server_cloud_annot.py      # 云端（可选 Data Platform）+ 本地 + 标注的统一入口
├─ foxglove_mcp_server.py                  # 早期混合版（保留做备份/参考）
└─ tests/
   └─ test_foxglove_mcp_server_local.py    # 本地能力的单测（生成最小 MCAP，跑核心工具）

推荐入口：

  • 仅本地：foxglove_mcp_server_local_annot.py
  • 需用 Data Platform：foxglove_mcp_server_cloud_annot.py

依赖与要求

  • Python 3.10+
  • 系统依赖：
    • ffmpeg（H264/H265 NAL → MP4 预览需要；OpenCV 写视频不强制）
  • Python 包（按需）：
    • 必需：mcap, foxglove-sdk, matplotlib, protobuf, plotly, mcp[cli]
    • 可选解码器：mcap-ros2-support, mcap-ros1-support, mcap-protobuf-support
    • 标注：opencv-python, pillow
    • Data Platform（仅云端版需要）：requests

使用 uv 安装

uv venv && source .venv/bin/activate
uv add "mcp[cli]" mcap foxglove-sdk matplotlib protobuf plotly opencv-python pillow \
       mcap-ros2-support mcap-ros1-support mcap-protobuf-support requests

不需要云端能力时，可去掉 requests。

环境变量

  • MCAP_BASE_DIRS（建议设置）：限制本地文件访问白名单（逗号分隔多路径）。未设置时默认仅允许当前工作目录。 
    export MCAP_BASE_DIRS="/data,/home/you/projects"
  • FOXGLOVE_API_BASE、FOXGLOVE_API_TOKEN（仅云端）：Foxglove Data Platform 接口与 Token。 
    export FOXGLOVE_API_BASE="https://api.foxglove.dev/v1"
export FOXGLOVE_API_TOKEN="fox_sk_********"

运行方式

开发模式（stdio）

# 本地+标注版
uv run mcp dev foxglove_mcp_server_local_annot.py
# 或
uv run python foxglove_mcp_server_local_annot.py stdio

# 云端+本地+标注版
uv run mcp dev foxglove_mcp_server_cloud_annot.py
# 或
uv run python foxglove_mcp_server_cloud_annot.py stdio

Cline/Cursor 等 IDE 代理会以 MCP 子进程 + stdio 方式启动本服务。

与 Cline / Cursor 集成

Cline（cline_mcp_settings.json）

{
  "mcpServers": {
    "foxglove-local": {
      "command": "/abs/path/to/python",
      "args": ["/abs/path/to/foxglove_mcp_server_local_annot.py", "stdio"],
      "env": {
        "MCAP_BASE_DIRS": "/data,/abs/workspace"
      },
      "alwaysAllow": [
        "mcap_info","mcap_list_topics","mcap_preview","mcap_trim",
        "mcap_timeseries","mcap_video_preview","csv_to_plotly_html",
        "image_annotate","video_annotate","start_live_server","log_json"
      ],
      "disabled": false
    },
    "foxglove-cloud": {
      "command": "/abs/path/to/python",
      "args": ["/abs/path/to/foxglove_mcp_server_cloud_annot.py", "stdio"],
      "env": {
        "MCAP_BASE_DIRS": "/data,/abs/workspace",
        "FOXGLOVE_API_BASE": "https://api.foxglove.dev/v1",
        "FOXGLOVE_API_TOKEN": "fox_sk_..."
      },
      "alwaysAllow": [
        "dp_list_topics","dp_download_data","dp_list_recordings",
        "mcap_info","mcap_list_topics","mcap_preview","mcap_trim",
        "mcap_timeseries","mcap_video_preview","csv_to_plotly_html",
        "image_annotate","video_annotate","start_live_server","log_json"
      ],
      "disabled": false
    }
  }
}

Cursor（.cursor/mcp.json）

{
  "mcpServers": {
    "foxglove": {
      "command": "/abs/path/to/python",
      "args": ["/abs/path/to/foxglove_mcp_server_local_annot.py", "stdio"],
      "env": {"MCAP_BASE_DIRS": "/data,/abs/workspace"}
    }
  }
}

工具方法一览（按类别）

本地 MCAP

  • mcap_info(path) → 读取 header/通道/Schema/时间范围
  • mcap_list_topics(path) → 按话题列出 channel_id/编码/Schema
  • mcap_preview(path, topic, start=None, end=None, limit=20, decode="raw|json") → 预览消息
  • mcap_trim(src_path, dst_path, topics=None, start=None, end=None) → 时间窗/话题裁剪到新 MCAP
  • mcap_timeseries(path, topic, field_path, start=None, end=None, csv_out=None, png_out=None, resample_hz=None, max_points=5e5, highlight_spans=None, highlight_boxes=None, highlight_points=None)
    • 字段取值：支持 a.b.c 与下标 poses[0].position.x
    • 解码：优先 iter_decoded_messages（Proto/ROS2/ROS1 解码器可选），回退 JSON
    • 输出：CSV（t_iso,t_ns,value），PNG（可 方框/时间窗/点 高亮）
    • 下采样：resample_hz 近似固定频率（bin 的最后一个样本）
  • mcap_video_preview(path, topic, mp4_out, codec="auto|h264|h265", start=None, end=None, fps=30)
    • 假设每条消息为完整访问单元（常见于 H264/H265 NAL 流）
    • ffmpeg remux，无重编码；自动探测编解码器

报告/可视化

  • csv_to_plotly_html(csv_path, html_out, x_col="t_iso", y_cols=None, title=None, highlight_spans=None, highlight_boxes=None, highlight_points=None)
    • 生成独立 HTML（Plotly），支持与 PNG 一致的高亮

图片/视频标注（OpenCV）

  • image_annotate(image_path, out_path=None, overlays=[...], coords_normalized=False)
  • video_annotate(src_path, dst_path, overlays=[...], coords_normalized=False, time_unit="sec|ms|frame", fps_out=None, fourcc="mp4v", max_frames=None)
    • overlay 支持：
      • {"type":"box","xywh":[x,y,w,h],"alpha":0.2,"color":"#FF0000","label":"..."}
      • {"type":"poly","points":[[x1,y1],[x2,y2],...],"alpha":0.2}
      • {"type":"circle","center":[x,y],"radius":r}
      • {"type":"line","points":[[x1,y1],[x2,y2]]}
      • {"type":"text","text":"hello","anchor":[x,y]}
    • 颜色：#RRGGBB / "r,g,b" / [b,g,r]；坐标可归一化

Data Platform（云端，可选）

  • dp_list_topics(ctx, device_id|device_name|recording_id, start, end, include_schemas=False, limit=2000, offset=0)
  • dp_download_data(ctx, topics=[...], output_format="mcap|bag1|mcap0", compression_format="lz4|zstd|", ...)
  • dp_list_recordings(ctx, device_id|device_name, topic, start, end, site_id, edge_site_id, ...)

快速示例

1) 时序抽取 + 高亮 → PNG/CSV

mcap_timeseries(
  path="/data/run1.mcap", topic="/vehicle/odom", field_path="twist.linear.x",
  csv_out="/tmp/odom_x.csv", png_out="/tmp/odom_x.png", resample_hz=10,
  highlight_spans=[{"start":"2025-07-30T17:05:06Z","end":"2025-07-30T17:05:08Z","label":"AEB"}],
  highlight_boxes=[{"start":"2025-07-30T17:05:06.5Z","end":"2025-07-30T17:05:07.2Z","ymin":-0.5,"ymax":0.5,"label":"异常"}],
  highlight_points=["2025-07-30T17:05:07Z"]
)

2) CSV → 交互式 HTML 报告

csv_to_plotly_html(
  csv_path="/tmp/odom_x.csv", html_out="/tmp/odom_x.html",
  x_col="t_iso", y_cols=["value"], title="twist.linear.x"
)

3) 从 MCAP 预览视频（H264/H265）

mcap_video_preview(
  path="/data/run1.mcap", topic="/camera/h264", mp4_out="/tmp/cam.mp4", codec="auto"
)

4) 图片/视频打框标注

image_annotate(
  image_path="/tmp/in.png", out_path="/tmp/out.png",
  overlays=[{"type":"box","xywh":[100,120,220,160],"alpha":0.2,"color":"#00FF00","label":"Target"}]
)

video_annotate(
  src_path="/tmp/in.mp4", dst_path="/tmp/out.mp4", time_unit="sec",
  overlays=[{"type":"box","xywh":[200,120,260,180],"start":2.5,"end":4.0,"color":"#FF0000","thickness":3,"label":"Brake"}]
)

5) 云端 topics / 导出（需要 Token）

dp_list_topics(ctx, device_name="dev_123", start="2025-07-01T00:00:00Z", end="2025-07-02T00:00:00Z", include_schemas=True)

测试

uv add pytest
pytest -q
  • tests/test_foxglove_mcp_server_local.py 会动态生成最小 MCAP，覆盖 mcap_info/list/preview/timeseries/trim/plotly 等路径。
  • 若 ffmpeg 不存在，视频预览测试会自动 skip。

常见问题与提示

  • 字段路径：支持 a.b.c 与数组下标 poses[0].position.x。
  • 解码器：
    • 安装 mcap-ros2-support / mcap-ros1-support / mcap-protobuf-support 即可对非 JSON 话题自动解码（iter_decoded_messages）。
  • 性能：
    • 大文件提取建议传 resample_hz 与 max_points，避免内存暴涨。
  • 安全：
    • 强烈建议设置 MCAP_BASE_DIRS；超出白名单的路径会被拒绝。
  • 视频预览：
    • 仅 remux，不重编码；要求 MCAP 中每条消息是完整访问单元（常见记录方式）。
  • OpenCV 编码：
    • video_annotate 默认 fourcc=mp4v，如遇编码器不可用，可尝试 avc1 或安装系统编码器。

变更记录（与上一轮需求）

  • ✨ 通用解码层：ROS1/ROS2/CDR/Protobuf 自动解码 → 非 JSON bag 同样可抽字段
  • ✨ 高亮标注：PNG/Plotly 支持时间窗、方框（time×value）与关键点
  • ✨ 图像/视频标注：OpenCV 实现 image_annotate / video_annotate
  • ✨ Cline/Cursor 配置：提供示例 JSON，可直接挂 MCP server
  • 🧪 单元测试：最小 MCAP 生成 + 核心功能覆盖

License

自用/内部工具，按需调整。