CCPhoto — Phone Camera Bridge

CCPhoto

通过本地网络将手机摄像头连接到 Claude Code。

CCPhoto 是一个 MCP 服务，可让你用手机拍照，并直接发送给 Claude Code。将手机对准电路板、白板、标签或任何物品，Claude 就能立即看到。无需安装应用；手机浏览器中的摄像头即可完成所有操作。

 +----------+        WiFi        +-----------+       MCP        +-------------+
 |  Phone   |  photos, voice,   |  CCPhoto  |   image/text     |  Claude     |
 |  Camera  |  mode switches    |  Server   |   data            |  Code       |
 |  + Mic   | <--------------- |  (local)  | <--------------- |             |
 +----------+   TTS, guidance   +-----------+   send_to_phone  +-------------+

快速开始

npx ccphoto --setup        # One-time: register CCPhoto as an MCP server

然后在 Claude Code 中说 “拍张照片”，剩下的交给 Claude 即可。

工作原理

1. Claude 调用 capture_photo MCP 工具。
2. 终端中会显示一个二维码。
3. 用手机扫描二维码，浏览器中会打开摄像头页面。
4. 拍照后，Claude 会直接收到图像。

无需安装应用。通过 <input capture> HTML 属性即可调用手机的原生摄像头。

常驻模式

服务器会在首次调用 capture_photo 时启动，并在整个会话期间保持运行。手机会保持连接，无需重新扫描二维码。想拍多少张都可以，也可以向 Claude 提问来获取其中任意一张照片。

拍照请求通知

手机已连接时，如果 Claude 再次调用 capture_photo，手机就会收到 SSE 推送通知。拍摄按钮会闪烁，提示 Claude 正在等待新照片。只需轻点按钮即可拍摄。

双向消息

Claude 可以使用 send_to_phone 工具向手机发送内容。文本、Markdown 和图像会显示在手机的可折叠面板中。这样手机就能用作参考屏幕——Claude 可以显示接线说明、引脚排列图或代码片段，让你腾出双手操作。

照片标注

拍照后会显示标注界面，你可以在发送前对图像进行绘制。使用彩色画笔（红色、蓝色、绿色、白色）圈出组件、绘制箭头或突出显示感兴趣的区域。轻点“发送”即可上传标注后的图像，或轻点“跳过”以发送未标注的原始照片。

实时视频助手

通过手机摄像头启动半实时视频流。Claude 会观看实时画面（每 3 秒一帧）并实时提供指导——将摄像头对准 Claude 指示的位置，并在手机屏幕上接收说明。

需要 HTTPS（用于访问摄像头）。在 Android Chrome 上，只需接受一次证书警告。目前仅支持 Android/Chrome；计划支持 iOS。

语音交互

轻点手机上的麦克风按钮即可与 Claude 语音交流。语音会通过浏览器内置的 Speech Recognition API 转录为文本并发送。Claude 可以通过在 send_to_phone 中使用 speak: true 发送语音回复，手机会通过文本转语音功能朗读回复。

这样就能实现免提工作流：拿着烙铁时提出问题，无需看屏幕即可听到答案。麦克风按钮仅会出现在支持 Speech Recognition 的浏览器中（Android Chrome）。

生成式 UI

Claude 可以根据看到的内容，在手机上生成丰富且符合上下文的 UI。将摄像头对准产品、组件、食谱或任何物品，Claude 会进行分析，并向手机屏幕发送自定义交互界面。

包含 12 种组件类型：Card、Text、Image、Metric、MetricGrid、Checklist、StepByStep、Alert、Table、Timer、Badge 和 Divider。Claude 会将这些组件组合成符合上下文的布局——例如，带浇水清单的植物养护卡片、带引脚图的电路组件表，或附有计时器的分步维修指南。

使用 send_to_phone 和 ui_spec 参数即可生成自定义 UI。

安装

npx（推荐，无需安装）

npx ccphoto --setup

全局安装

npm install -g ccphoto
ccphoto --setup

源码

git clone https://github.com/stepankaiser/ccphoto.git
cd ccphoto
npm install
npm run build
node dist/index.js --setup

如果您希望手动注册 MCP 服务，而不是使用 --setup：

claude mcp add ccphoto -- npx ccphoto --mcp

MCP 工具参考

工具	描述	参数
capture_photo	启动服务并显示二维码。如果已有手机连接，则改为向其发送推送通知。	--
wait_for_photo	阻塞等待照片上传或超时。请在调用 capture_photo 后立即调用此工具。	timeout_seconds（可选，默认值：120）
get_latest_photo	返回最新照片，或按文件名返回指定照片。	filename（可选）
list_photos	列出所有已拍摄照片的文件名、时间戳和大小。	--
send_to_phone	向手机屏幕发送文本、图片或丰富的生成式 UI。手机可作为说明、图表或引脚排列图的参考屏幕。	text、image_base64、image_mime_type、speak、ui_spec（均可选）
start_livestream	启动手机摄像头的实时视频流。生成 HTTPS 证书并返回二维码。	--
get_live_frame	获取实时摄像头视频流的最新画面，并附带新鲜度时间戳。	--

独立 CLI 模式

CCPhoto 也可以独立运行，无需 Claude Code：

npx ccphoto                                  # Start with defaults
npx ccphoto --port 4000 --output-dir ./photos  # Custom port and directory

终端中会显示二维码。扫描二维码并拍摄照片，照片将保存到磁盘。 服务会持续运行，以便多次拍摄。

CLI 选项

选项	描述	默认值
--setup	在 Claude Code 中将 CCPhoto 注册为 MCP 服务	--
--mcp	作为 MCP 服务运行（由 Claude Code 在内部使用）	--
--port <number>	HTTP 服务端口	3847
--output-dir <path>	照片保存目录	~/.ccphoto/captures/
--help	显示帮助	--

配置

环境变量	描述	默认值
CCPHOTO_DIR	覆盖默认照片存储目录	~/.ccphoto/captures/

安全性

• 会话令牌 -- 每个服务会话都会生成一个经过加密学安全随机生成的 32 位十六进制令牌。每个请求都必须包含该令牌。
• 时序安全比较 -- 令牌验证使用 crypto.timingSafeEqual，以防止时序攻击。
• 仅限本地网络 -- 服务绑定到您的本地网络 IP。数据不会离开您的网络。
• 无外部服务 -- 照片通过局域网 HTTP 在手机和服务之间直接传输。不会上传到云端。

故障排除

无法检测本地网络 IP

确保您的电脑已连接 WiFi（某些配置下，仅连接以太网可能不够）。CCPhoto 需要一个手机可以访问的局域网 IP 地址。

无法扫描二维码

尝试增大终端字体，或缩小终端宽度，让二维码以可扫描的分辨率显示。您也可以复制二维码下方显示的 URL，并在手机浏览器中手动输入。

手机摄像头无法打开

某些浏览器的拍摄功能需要 HTTPS，但大多数移动浏览器允许在本地网络地址上使用普通 HTTP。如果浏览器阻止访问摄像头，请尝试使用 Safari（iOS）或 Chrome（Android）。

上传失败

请确认手机和电脑连接到同一个 WiFi 网络。启用了客户端隔离的企业网络可能会阻止设备间通信。请尝试使用个人热点或家庭网络。

开发

npm install          # Install dependencies
npm run build        # Compile TypeScript
npm run dev          # Watch mode (recompile on change)
npm test             # Run the test suite (94 tests)

测试使用 Node.js 内置的测试运行器，并需要 tsx 开发依赖来执行 TypeScript。

项目结构：

src/
  index.ts        CLI entry point and arg parsing
  mcp.ts          MCP server with tool definitions
  server.ts       HTTP server, SSE, upload handling
  mobile-page.ts  Self-contained HTML for the phone camera page
  storage.ts      Photo file management
  network.ts      Local IP detection
  token.ts        Session token generation and validation
  types.ts        Shared TypeScript interfaces

路线图

• 真实域名 + Let's Encrypt 证书——使用已注册的域名和有效证书，让任何设备（包括 iOS Safari）都不会出现浏览器警告。
• 支持 iOS 实时视频——实时视频流目前可在 Android/Chrome 上使用。iOS Safari 需要受信任的证书才能支持。
• 在摄像头画面上叠加 AR——实时直接在摄像头画面上绘制注释。
• 支持多摄像头——同时连接多部手机，以提供不同的视角。
• WebRTC 流式传输——待 Claude 的视觉处理延迟改善后，用 WebRTC 取代 HTTP 帧轮询。

贡献

欢迎贡献。

1. Fork 此仓库
2. 创建功能分支（git checkout -b my-feature）
3. 进行更改
4. 运行 npm test，验证一切正常
5. 提交更改（git commit -m "Add my feature"）
6. 推送到你的分支（git push origin my-feature）
7. 发起拉取请求

报告 Bug 时，请附上你的 Node.js 版本、操作系统以及复现问题的步骤。

许可证

MIT