CCPhoto

Bridge your phone camera to Claude Code over the local network.

CCPhoto는 휴대폰에서 사진을 찍어 Claude Code로 직접 보낼 수 있게 해주는 MCP 서버입니다. 휴대폰을 회로 기판, 화이트보드, 라벨 등 어떤 대상에든 비추면 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. 터미널에 QR 코드가 나타납니다.

3. 휴대폰으로 QR 코드를 스캔하면 브라우저에 카메라 페이지가 열립니다.

4. 사진을 찍으면 Claude가 이미지를 직접 받습니다.

앱 설치는 필요 없습니다. 휴대폰 기본 카메라는 <input capture> HTML 속성을 통해 접근됩니다.

상시 실행 모드

서버는 첫 번째 capture_photo 호출 시 시작되어 전체 세션 동안 계속 실행됩니다. 휴대폰은 연결된 상태를 유지하므로 QR 코드를 다시 스캔할 필요가 없습니다. 원하는 만큼 사진을 찍고, Claude에게 요청하여 그중 아무 사진이나 가져올 수 있습니다.

사진 요청 알림

휴대폰이 이미 연결된 상태에서 Claude가 capture_photo를 다시 호출하면 휴대폰이 SSE 푸시 알림을 받습니다. 캡처 버튼이 깜빡이며 Claude가 새 사진을 기다리고 있음을 알려줍니다. 그냥 탭하여 촬영하면 됩니다.

양방향 메시징

Claude는 send_to_phone 도구를 사용하여 휴대폰으로 콘텐츠를 보낼 수 있습니다. 텍스트, 마크다운, 이미지가 휴대폰의 접이식 패널에 표시됩니다. 이렇게 하여 휴대폰이 참조 화면이 됩니다. Claude가 배선 지침, 핀아웃 다이어그램, 코드 조각을 표시하는 동안 양손으로 작업할 수 있습니다.

사진 주석

사진을 찍으면 전송하기 전에 이미지 위에 그림을 그릴 수 있는 주석 화면이 나타납니다. 색상 펜(빨강, 파랑, 초록, 흰색)으로 부품에 원을 그리거나, 화살표를 그리거나, 관심 영역을 강조할 수 있습니다. "전송"을 탭하면 주석이 추가된 이미지를 업로드하고, "건너뛰기"를 탭하면 주석 없이 원본 사진을 전송합니다.

라이브 비디오 어시스턴트

휴대폰 카메라에서 반실시간 비디오 스트림을 시작합니다. Claude가 라이브 피드(3초마다 1프레임)를 보면서 실시간으로 안내를 제공합니다. Claude가 요청하는 곳으로 카메라를 비추면 휴대폰 화면에서 지침을 받을 수 있습니다.

HTTPS가 필요합니다(카메라 접근용). Android Chrome에서는 인증서 경고를 한 번 수락하세요. 현재 Android/Chrome만 지원하며 iOS 지원은 계획 중입니다.

음성 상호작용

휴대폰의 마이크 버튼을 탭하여 Claude에게 말하세요. 음성은 브라우저에 내장된 Speech Recognition API를 사용하여 텍스트로 변환된 후 전송됩니다. Claude는 speak: true와 함께 send_to_phone을 사용하여 음성 오디오로 응답할 수 있습니다. 그러면 휴대폰이 Text-to-Speech를 통해 응답을 소리 내어 읽어 줍니다.

이를 통해 핸즈프리 워크플로우가 가능합니다. 인두기를 들고 있는 동안 질문하고, 화면을 보지 않고 답을 들을 수 있습니다. 마이크 버튼은 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

--setup을 사용하는 대신 MCP 서버를 수동으로 등록하려면:

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

QR 코드가 터미널에 출력됩니다. 스캔하여 사진을 찍으면 디스크에 저장됩니다. 서버는 여러 번의 캡처 동안 계속 실행됩니다.

CLI 옵션

구성

보안

• 세션 토큰 -- 각 서버 세션에 대해 암호학적으로 무작위한 32자리 16진수 토큰이 생성됩니다. 모든 요청에는 이 토큰이 포함되어야 합니다.

• 타이밍 안전 비교 -- 토큰 검증은 타이밍 공격을 방지하기 위해 crypto.timingSafeEqual을 사용합니다.

• 로컬 네트워크 전용 -- 서버는 로컬 네트워크 IP에 바인딩됩니다. 어떤 데이터도 네트워크를 벗어나지 않습니다.

• 외부 서비스 없음 -- 사진은 LAN의 HTTP를 통해 휴대폰과 서버 간에 직접 전송됩니다. 클라우드에 업로드되는 것은 없습니다.

문제 해결

로컬 네트워크 IP를 감지할 수 없는 경우

컴퓨터가 WiFi에 연결되어 있는지 확인하세요(일부 구성에서는 이더넷만으로는 충분하지 않습니다). CCPhoto에는 휴대폰이 접근할 수 있는 LAN IP 주소가 필요합니다.

QR 코드가 스캔되지 않는 경우

QR 코드가 스캔 가능한 해상도로 렌더링되도록 터미널 글꼴 크기를 키우거나 터미널 너비를 줄여 보세요. QR 코드 아래에 출력된 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 내장 테스트 러너를 사용하며 TypeScript 실행을 위해 tsx 개발 의존성이 필요합니다.

프로젝트 구조:

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의 비전 처리 지연 시간이 개선되면 HTTP 프레임 폴링을 WebRTC로 대체합니다.

기여

기여를 환영합니다.

1. 저장소를 포크합니다.

2. 기능 브랜치를 만듭니다 (git checkout -b my-feature).

3. 변경 사항을 적용합니다.

4. npm test를 실행하여 문제가 없는지 확인합니다.

5. 변경 사항을 커밋합니다 (git commit -m "Add my feature").

6. 브랜치로 푸시합니다 (git push origin my-feature).

7. 풀 리퀘스트를 엽니다.

버그를 보고할 때는 Node.js 버전, OS, 그리고 문제를 재현하는 단계를 포함해 주세요.

라이선스

MIT