open-eagle-eye

Open Eagle Eye

为 AI Agent 提供全球公共摄像头实时画面的 MCP 服务。一次 HTTP GET，即可在不到一秒内获取图像；无需浏览器自动化，也无需解码视频流。

为什么要使用

大多数摄像头 API 都要求身份验证、提供视频流，或将图像隐藏在 JavaScript 渲染的页面后面。Open Eagle Eye 只索引通过普通 HTTP GET 请求返回 JPEG 或 PNG 的摄像头——这是最简单的集成方式。Agent 无需渲染页面或解码视频，只需获取图像即可。

注册表具有自我修复能力。GitHub Action 每晚运行，检查每个摄像头，并在移除失效摄像头前重试；它还会使用视觉 AI 检查摄像头是否返回错误页面而非实时画面。失效摄像头会被自动标记。

快速开始

{
  "mcpServers": {
    "openeagleeye": {
      "command": "npx",
      "args": ["-y", "openeagleeye"]
    }
  }
}

也可以全局安装：

npm install -g openeagleeye
openeagleeye

首次运行时，服务会从 GitHub 获取最新摄像头注册表，并将其缓存在本地的 ~/.openeagleeye/ 中。之后每次启动都会自动刷新缓存。

工作原理

任何通过普通 HTTP GET 请求返回 JPEG 或 PNG 的端点，都是有效的摄像头 URL。大多数城市交通摄像头、气象站和公园摄像头都提供此类端点。服务会获取图像、将其保存到磁盘，并返回文件路径。

MCP 工具

工具	描述
get_snapshot	获取摄像头的实时图像并保存到磁盘，返回文件路径
list_cameras	使用筛选条件（城市、位置、类别）浏览注册表
search_cameras	按名称、位置或类别搜索
add_local_camera	将摄像头添加到本地集合
list_local	显示本地添加的摄像头
remove_local	删除本地添加的摄像头
submit_local	通过 GitHub issue 将本地摄像头分享至上游
report_camera	举报失效或画质较差的摄像头
check_config	显示 API 密钥配置状态

上游摄像头与本地摄像头

注册表分为两层：

• 上游 — 每次服务启动时从 GitHub 获取的全局注册表。这些是约 32,000 个经过验证的公共摄像头。
• 本地 — 你通过 add_local_camera 自行添加的摄像头。它们保存在 ~/.openeagleeye/local-cameras.json 中，重启后仍会保留，并在 list_cameras/search_cameras 中以 source: "local" 显示。你可以随时通过 submit_local 将它们分享至上游。

筛选

每个摄像头都有一个 city 字段。使用 list_cameras 并设置 city: "Sydney"，即可获取精简且相关的列表，而不是将所有摄像头都输出到上下文中。

输出格式

每个工具都会返回结构化 JSON。快照会保存到磁盘并返回文件路径——MCP 服务作为本地子进程运行，因此 Agent 可以访问文件系统。

快照响应：

{
  "success": true,
  "file_path": "/home/user/.openeagleeye/snapshots/a1b2c3d4e5f6a7b8.jpg",
  "size_bytes": 14579,
  "content_type": "image/jpeg",
  "camera": {
    "id": "nyc-bb-21-north-rdwy-at-above-south-st",
    "name": "BB-21 North Rdwy @ Above South St",
    "city": "New York",
    "location": "Manhattan, New York, USA",
    "coordinates": { "lat": 40.708, "lng": -73.999 }
  }
}

注册表

覆盖 11 个国家的约 32,000 个摄像头（已验证 32,096 个）：

国家/地区	数量	来源
US	27,184	NYC DOT、NY 511、WSDOT、Caltrans CWWP2、CDOT CoTrip、VDOT 511、FDOT FL511、NCDOT、PennDOT 511PA、Arizona ADOT、Oregon ODOT、Nevada NDOT、Utah UDOT、Wisconsin WisDOT、New England 511、Louisiana LADOTD、Alaska DOT&PF、Missouri MoDOT
FI	1,309	Digitraffic 气象摄像头（Fintraffic）
CA	1,292	Ontario MTO、Alberta 511
HK	995	Hong Kong Transport Department
GB	424	London TfL JamCams
NZ	248	NZTA 全国高速公路
AU	247	Queensland DOT 交通与洪水摄像头
BR	160	CET São Paulo 城市交通
JP	98	NEXCO East 高速公路
SG	90	Singapore LTA
IE	49	TII 高速公路摄像头（M50 Dublin）

每个摄像头都有 country、city、location、timezone 和 coordinates（纬度/经度）。

自愈

GitHub Action 每晚 UTC 时间 3 点运行：

• 检查过去 7 天内未验证的摄像头，以及所有被标记为疑似异常的摄像头
• 首次失败时标记为疑似异常，连续第二次失败时移除并创建 GitHub issue
• Vision AI（通过 GitHub Models 使用 GPT-4o-mini）可识别返回错误页面的摄像头
• 恢复正常的疑似异常摄像头会自动解除标记

安全性

• SSRF 防护 — 阻止私有 IP、云元数据端点、非 HTTP 协议和 DNS 重绑定
• 内容类型白名单 — 仅接受 image/jpeg 和 image/png
• 魔数检测 — CDN 返回错误的内容类型时，根据文件头验证 JPEG/PNG
• 推送/PR 上限 — 每次推送最多 500 个摄像头，防止通过过大的 PR 发起 DoS 攻击
• 随机文件名 — 快照使用随机十六进制文件名，路径中不包含摄像头 ID

API 密钥（可选）

大多数摄像头开箱即用。部分摄像头需要免费的 API 密钥。如果快照因密钥错误而失败，响应会告诉你在哪里注册以及如何配置。

创建 ~/.openeagleeye/config.json：

{
  "api_keys": {
    "PROVIDER_API_KEY": "your-key-here"
  }
}

使用 check_config 查看哪些摄像头需要密钥，以及你是否已设置相应密钥。

添加摄像头

1. 找到直接图像 URL（通过普通 GET 请求必须返回 image/jpeg 或 image/png）
2. 使用 URL、城市、位置、时区和可选坐标调用 add_local_camera
3. 调用 get_snapshot 进行测试
4. 调用 submit_local 向上游提交 — 需要 gh CLI（gh auth login）

本地摄像头添加后即可立即使用，无需获得上游批准。

良好的来源：城市 DOT、气象站、滑雪场、国家公园、港口、机场。

文件布局

所有运行时数据都位于 ~/.openeagleeye/：

~/.openeagleeye/
  cameras.json          # Upstream registry (fetched from GitHub on boot)
  local-cameras.json    # Your locally-added cameras
  .registry-state.json  # Validation state (active/suspect/offline)
  snapshots/            # Downloaded camera images
  config.json           # API keys

贡献

欢迎提交拉取请求。添加摄像头来源的指南请参阅 CONTRIBUTING.md。

项目缘起

请参阅 WHY.md，了解项目设计决策背后的原因、它与其他摄像头服务的比较，以及为什么 Agent 原生和自愈能力很重要。

隐私与安全

请参阅 SECURITY.md，了解有关监控、数据收集、私人摄像头和安全架构的常见问题解答。

许可证

MIT