Webcam MCP

分支说明。 这是 botbridge-webcam-mcp，是 pavel-kirienko/webcam_mcp（MIT）的一个分支， 由 1019666077-bit 维护。它新增了 MCP Apps 面板（webcam_panel）。请将此发行版安装为 botbridge-webcam-mcp；上游在 PyPI 上的发行版名为 webcam-mcp。Python 导入包名为 webcam_mcp。

---

Webcam MCP 是一种模型上下文协议（MCP）服务，可让大模型 Agent 直接访问你的摄像头。它支持自主 Agent 拍摄照片和录制视频片段，从而无需人工干预即可调试信息物理系统、监控环境并与物理世界交互。

功能：

• 📸 高分辨率照片：拍摄静态图像
• 🎛️ MCP Apps 面板（webcam_panel）：免费的聊天内按钮（拍一张 / 再拍 / 关掉）；仅提供 Pro 占位项
• 🎥 视频录制：在指定时长内录制一系列帧
• 🌐 SSE 传输：默认仅限环回；可选择启用 LAN 暴露，且无身份验证
• ⚙️ 可配置：调整分辨率、摄像头索引和画质设置
• 🔌 跨平台：支持 Linux、macOS 和 Windows
• 🚀 易于集成：MCP 客户端配置简单

使用方法

安装：

pip install botbridge-webcam-mcp

启动 MCP 服务：

webcam-mcp

服务默认在 http://127.0.0.1:8000/sse 启动（仅限环回）。

你可以使用任意 MCP 客户端测试服务，例如 MCP Inspector（通过 npx @modelcontextprotocol/inspector 安装）。

CLI 选项

选项	类型	默认值	说明
--host	string	127.0.0.1	服务主机地址
--port	integer	8000	服务端口
--camera-index	integer	0	摄像头设备索引
--photo-width	integer	1920	默认照片宽度（像素）
--photo-height	integer	1080	默认照片高度（像素）
--video-width	integer	640	默认视频帧宽度（像素）
--video-height	integer	480	默认视频帧高度（像素）
--version	-	-	显示版本并退出

示例

# Start on custom port
webcam-mcp --port 9000

# Use different camera (e.g., external USB webcam)
webcam-mcp --camera-index 1

# Custom photo resolution
webcam-mcp --photo-width 1280 --photo-height 720

# Opt-in LAN exposure (unauthenticated! see Security below)
WEBCAM_MCP_ALLOW_LAN=1 webcam-mcp --host 0.0.0.0

安全性

SSE 传输没有身份验证。任何能够访问 SSE 端点的人，都可以触发你的摄像头拍照和录制视频。

• 优先使用 stdio（桌面 MCP 客户端会自动使用），或使用环回地址 （默认值为 127.0.0.1）。
• 将 --host 绑定到非环回地址（例如 0.0.0.0 或 LAN IP）时，启动时会打印醒目的警告，且除非设置 WEBCAM_MCP_ALLOW_LAN=1，否则会拒绝启动。
• 只有在了解风险，并且已在服务前配置自己的身份验证时，才应将服务暴露在 LAN 或公共网络接口上。

MCP 客户端配置

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "webcam": {
      "url": "http://localhost:8000/sse"
    }
  }
}

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

其他 MCP 客户端

任何支持 SSE 传输的 MCP 客户端都可以连接到：

http://<host>:<port>/sse

MCP 工具

take_photo

使用摄像头拍摄一张高分辨率照片。

参数： 无

返回： JPEG 图像

Claude 中的使用示例：

Can you take a photo and describe what you see?

record_video

在指定时长内录制视频帧。

参数：

• duration_seconds（float，可选）：录制时长，单位为秒
  • 最短：1.0 秒
  • 最长：60.0 秒
  • 默认值：5.0 秒

返回： JPEG 帧列表

在 Claude 中的示例用法：

Record a 10-second video and analyze any movement you detect.

故障排除

摄像头权限被拒绝（macOS）

在 macOS 上，你需要授予摄像头权限：

1. 打开系统设置 → 隐私与安全性 → 摄像头
2. 为 Terminal（或你的终端应用）启用摄像头访问权限
3. 重启终端并重试

摄像头已在使用

如果看到“摄像头不可用”错误：

1. 关闭其他正在使用网络摄像头的应用程序（Zoom、Skype 等）
2. 检查是否有其他 webcam-mcp 实例正在运行
3. 尝试使用其他摄像头索引：webcam-mcp --camera-index 1

摄像头索引错误

查找可用摄像头：

import cv2
for i in range(10):
    cap = cv2.VideoCapture(i)
    if cap.isOpened():
        print(f"Camera {i}: Available")
        cap.release()
    else:
        print(f"Camera {i}: Not available")

然后使用 --camera-index 并指定正确的编号。

不支持该分辨率

如果摄像头不支持请求的分辨率，服务将：

• 记录警告，并显示实际采用的分辨率
• 继续使用摄像头支持的最高分辨率运行

检查日志中是否有类似以下的消息：

WARNING: Requested resolution 1920x1080, but camera provided 1280x720

开发

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_camera.py

所有测试均使用模拟摄像头硬件，因此测试不需要实体网络摄像头。

发布

要标记并发布新版本，请向 main 推送一个包含新 __version__ 字符串的提交。 这将触发新的标签创建，并将新版本推送到 PyPI。