SightRadar

SightRadar MCP 服务

为 AI 助手提供人脸识别功能。为活动照片建立索引，通过一张自拍查找某人出现过的所有照片，批量运行、管理 Webhook 和账单；一切操作都可在 Claude、ChatGPT、Cursor、VS Code 或任何 MCP 客户端中完成。

---

有两种连接方式，两者提供相同的工具。

	远程（托管）	本地（此软件包）
URL / 命令	https://mcp.sightradar.com/mcp	npx -y sightradar-mcp
登录	SightRadar 账户（邮箱 + 密码、Google 或邮箱链接），或将 API 密钥用作 Bearer 令牌	SIGHTRADAR_API_KEY
安装	无需安装	Node.js 20+
电脑中的图像	不支持（使用 URL 或 base64）	支持，使用 file_path

远程服务（推荐）

添加 https://mcp.sightradar.com/mcp 作为自定义连接器。首次使用时，浏览器会打开 sightradar.com；登录后即可选择允许助手执行的操作。每个连接都会获得独立的可撤销密钥，列在 API keys 下，名称为 MCP: <app name>。

• Claude（claude.ai、Desktop）：Settings → Connectors → Add custom connector → 粘贴 URL。
• ChatGPT：Settings → Apps & Connectors → Create → 粘贴 URL，身份验证方式选择 OAuth。
• Claude Code：claude mcp add --transport http sightradar https://mcp.sightradar.com/mcp
• Cursor（~/.cursor/mcp.json）/ VS Code（.vscode/mcp.json，键 servers）：

  { "mcpServers": { "sightradar": { "url": "https://mcp.sightradar.com/mcp" } } }
  

想使用 API 密钥？将其作为请求头发送，无需登录：

{
  "mcpServers": {
    "sightradar": {
      "url": "https://mcp.sightradar.com/mcp",
      "headers": { "Authorization": "Bearer frs_your_key" }
    }
  }
}

本地服务

在 sightradar.com/dashboard/keys 创建 API 密钥，然后：

{
  "mcpServers": {
    "sightradar": {
      "command": "npx",
      "args": ["-y", "sightradar-mcp"],
      "env": { "SIGHTRADAR_API_KEY": "frs_your_key" }
    }
  }
}

此配置块适用于 Claude Desktop（claude_desktop_config.json）、Cursor、Windsurf、Cline 和大多数客户端。Claude Code：

claude mcp add sightradar --env SIGHTRADAR_API_KEY=frs_your_key -- npx -y sightradar-mcp

变量	默认值
SIGHTRADAR_API_KEY	（必填）	API 密钥
SIGHTRADAR_SCOPES	read,search,write,delete	要公开的工具组。all 会添加 account；read 会提供只读服务。
SIGHTRADAR_FILE_ROOTS	你的主文件夹	file_path 可读取的文件夹（macOS/Linux 使用 : 分隔，Windows 使用 ; 分隔）。none 会禁用 file_path。
SIGHTRADAR_BASE_URL	https://api.sightradar.com	API 基础 URL
SIGHTRADAR_TIMEOUT_MS	120000	每个请求的超时时间
SIGHTRADAR_DEBUG	未设置	将每次工具调用记录到 stderr（不记录参数或结果）

工具

额度：100,000 个额度 = US$1。每个计费工具都会在其说明中注明价格，并接受 idempotency_key，因此重试不会被重复收费。

读取 — 免费

工具
list_collections	集合及其照片、人脸和自拍照数量；支持搜索和分页
get_collection	单个集合的状态和数量（verify 会从向量存储中重新统计）
get_deletion_status	集合删除进度
list_batches / get_batch / get_batch_photos	批处理任务、状态（一次查询 1 至 5000 个）和每张照片的结果
list_webhooks / list_webhook_failures	Webhook 端点和进入死信队列的投递
get_balance / get_usage	额度余额；使用情况摘要、每日序列或存储用量

搜索 — 消耗额度，不存储任何内容

工具	额度
search_faces	93	查找集合中所有包含自拍照（或嵌入向量）中人物的照片
search_by_point_id	62	无需重新发送自拍照，即可重复搜索已注册的自拍照
detect_faces	93	检测图像中的人脸、边界框和质量
compare_faces	每张图像 93	两张人脸是否属于同一个人？

写入 — 消耗额度 / 存储数据

工具	额度
index_photo	93	将照片中的人脸存储到集合中
register_selfie	93	存储某人的自拍照；返回其点 ID 和嵌入向量
submit_batch	每张照片 62	最多提交 1000 个照片 URL，用于索引或匹配；在后台处理
requeue_failed_batch_photos	每张照片 62	重试失败的批处理照片（先预览，再执行）
create_collection / recreate_collection	免费
create_webhook / replay_webhook_failures	免费	接收批处理和删除事件的签名投递

删除 — 免费

工具
delete_collection	软删除，默认提供 7 天恢复期；immediate 或 compliance 会永久擦除
restore_collection	撤销软删除
delete_photo / restore_photo	移除或恢复一张照片中的人脸
delete_webhook	停止向某个端点投递

账户 — 免费，在本地服务上默认关闭

工具
list_api_keys / create_api_key / revoke_api_key	API 密钥
get_profile / update_profile	姓名和组织
get_billing_settings / update_auto_recharge / get_invoice	自动充值、订单和发票 PDF
get_notification_settings / update_notification_settings / manage_notification_recipient	电子邮件提醒和额外收件人
list_team_members	组织成员

提示词和资源

能够显示 MCP 提示词的客户端（Claude 的“+”菜单、/ 命令）可使用三个现成的工作流：

提示词	功能
find_person_in_event	检查余额，使用自拍照搜索集合，并列出匹配的照片
index_event_photos	根据照片数量选择 index_photo 或 submit_batch，并在开始前说明费用
account_health	余额、近期使用情况、失败的批处理照片和失败的 Webhook 投递

资源：sightradar://docs/pricing-and-limits（每项操作的额度、速率限制、图像和删除限制）以及 sightradar://collections/{collection_id}（单个集合的数量，需要 read 范围）。

图像

图像工具只能且必须提供以下其中一项：

• image_url：公开的 http(s) URL。SightRadar 会下载图像，因此该 URL 必须能从互联网访问。
• gcs_key：您账户所配置 CDN 上的对象键。
• image_base64：以 base64 表示的字节数据或 data: URL。远程服务最多接受 10 MB；本地服务最多接受 30 MB。
• file_path（仅限本地服务）：位于 SIGHTRADAR_FILE_ROOTS 中的 JPEG、PNG、WebP、GIF、BMP、TIFF 或 HEIC 文件。

文件和 base64 数据都会先经过检查，确认是有效图像后才会上传。

示例提示词

• “创建一个名为 wedding-2026-10 的集合，并为 ~/Pictures/wedding 中的每张照片建立索引。”
• “这是 Priya 的自拍照：wedding-2026-10 中有哪些照片里有她？”
• “将这 600 个照片 URL 作为批次提交到 marathon-7，完成后告诉我。”
• “我这周用了多少积分，分别用在了什么地方？”
• “删除 test-event 集合。”（助手会先确认，且删除操作可在 7 天内撤销。）

安全

• 工具带有 MCP 注释（readOnlyHint、destructiveHint），因此客户端可在执行破坏性调用前询问。
• 默认执行软删除。必须显式设置 immediate 或 compliance 才会永久擦除。
• 作用域限制连接可执行的操作。仅具备 read 权限的连接无法使用积分或更改数据。
• 本地服务只会读取 SIGHTRADAR_FILE_ROOTS 中的文件夹内的文件；读取前会解析符号链接，且只读取图像文件。
• API 错误会作为工具结果返回，其中包含错误代码、提示和请求 ID，而不会返回堆栈跟踪。

故障排查

你看到的内容	含义
401 / unauthorized	API 密钥已被撤销或输入有误。请在 sightradar.com/dashboard/keys 创建新密钥；远程连接则重新连接。
402 / insufficient_credits	请在 sightradar.com/dashboard/billing 充值。
409 / duplicate_request_already_processed	该 idempotency_key 已使用并扣费；之前的调用已成功。
file_path ... is outside the folders this server may read	将该文件夹添加到 SIGHTRADAR_FILE_ROOTS 中（macOS/Linux 上以 : 分隔，Windows 上以 ; 分隔）。
429	每个密钥的请求速率超过 50 次/秒，或每个账户有 10 个并发请求。请等待后重试。

开发

npm install
npm test          # unit tests against a mocked API
npm run build
SIGHTRADAR_API_KEY=frs_... node scripts/smoke.mjs   # free live calls over stdio

导出了 createSightRadarServer({ api, scopes }) 和 TOOLS，可将相同的工具嵌入其他宿主。

链接

• SightRadar · API 文档 · 定价
• Node.js SDK：sightradar on npm · Python SDK：sightradar on PyPI

采用 MIT 许可证。