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。

Related MCP server: Xcode MCP Server

工作原理

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 可以使用带 speak: true 的 send_to_phone 以语音音频回复——手机会通过文本转语音功能大声朗读回复。

这让你无需动手也能完成工作：拿着烙铁时提问，不用看屏幕就能听到答案。麦克风按钮只出现在支持语音识别的浏览器上（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 工具参考

独立 CLI 模式

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

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

二维码会打印到终端。扫描二维码、拍照，照片会保存到磁盘。服务器会持续运行，支持多次拍摄。

CLI 选项

配置

安全

• 会话令牌——每个服务器会话都会生成一个加密随机的 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