Google 포토 MCP 서버

Google 포토 통합을 위한 MCP(Model Context Protocol) 서버로, Claude, Gemini 및 기타 AI 어시스턴트가 Google 포토 라이브러리의 사진을 읽고, 쓰고, 선택할 수 있게 합니다.

✅ Picker API 지원 (2025년 3월 이후)

이 서버는 Google 포토 Picker API를 구현하여, 2025년 3월 31일부로 특정 Library API 범위가 지원 중단된 이후에도 전체 라이브러리에 대한 액세스를 제공합니다.

Picker API 작동 방식

1. create_picker_session 호출 — 사용자가 브라우저에서 열 수 있는 URL을 반환합니다.

2. 사용자가 전체 라이브러리에서 사진을 선택합니다.

3. poll_picker_session 호출 — mediaItemsSet이 true가 되면 선택된 사진들이 반환됩니다.

Related MCP server: CoreViz MCP

🛡️ 보안 공지: CORS 제거됨

보안을 위해 CORS 미들웨어가 제거되었습니다(localhost에 대한 드라이브 바이 공격 방지).

• ✅ STDIO 모드 (Claude Desktop): 정상 작동

• ✅ Streamable HTTP (Cursor, 서버 간 통신): 정상 작동

• ❌ 브라우저 AJAX: 지원되지 않음 (설계상)

기능

읽기 작업

• 텍스트, 날짜, 위치, 카테고리, 즐겨찾기별 사진 검색

• 미디어 유형(사진/동영상), 날짜 범위, 보관 상태별 필터링

• base64 인코딩 이미지를 포함한 사진 상세 정보 가져오기

• 앨범 및 앨범 콘텐츠 목록 조회

• 사용 가능한 필터 기능 설명

쓰기 작업

• 앨범 생성 및 사진 업로드

• create_album_with_media를 통한 일괄 업로드 (최대 50개 파일)

• 앨범에 텍스트 및 위치 정보 추가

• 앨범 커버 사진 설정

Picker 작업

• 전체 라이브러리 액세스를 위한 Picker 세션 생성

• 세션 폴링 및 선택된 미디어 항목 가져오기

인프라

• ⚡ Streamable HTTP 전송 (MCP 2025-06-18 사양)

• 🔗 연결 풀링을 통한 HTTPS Keep-Alive

• 🔒 OS 키체인 토큰 저장

• 📊 자동 추적을 통한 할당량 관리

• 🔄 자동 토큰 갱신

사전 요구 사항

• Node.js 22.22 이상

• Photos Library API가 활성화된 Google Cloud 프로젝트

• OAuth 2.0 자격 증명 (웹 애플리케이션 유형)

설정

1. Google Cloud 설정

1. Google Cloud Console로 이동합니다.

2. 새 프로젝트를 생성하거나 기존 프로젝트를 선택합니다.

3. Photos Library API를 활성화합니다.

4. OAuth 2.0 자격 증명(웹 애플리케이션)을 생성합니다.

5. http://localhost:3000/auth/callback을 승인된 리디렉션 URI로 추가합니다.

6. 클라이언트 ID와 클라이언트 보안 비밀번호를 기록해 둡니다.

2. 설치

git clone https://github.com/savethepolarbears/google-photos-mcp.git
cd google-photos-mcp
npm install

3. 구성

cp .env.example .env

.env 파일 편집:

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback
PORT=3000
NODE_ENV=development

4. 빌드 및 실행

npm run build    # Compile TypeScript
npm start        # HTTP mode (for auth & Cursor)
npm run stdio    # STDIO mode (for Claude Desktop)
npm run dev      # Dev mode with live reload

5. 인증

1. HTTP 모드로 시작: npm start

2. 브라우저에서 http://localhost:3000/auth를 방문합니다.

3. Google OAuth 흐름을 완료합니다.

4. 토큰이 OS 키체인에 자동으로 저장됩니다.

참고: 인증은 먼저 HTTP 모드에서 완료해야 합니다. 그 후 Claude Desktop을 위해 STDIO 모드로 전환하십시오.

동적 포트

PORT=3001 npm start
# Also update GOOGLE_REDIRECT_URI in .env to match

클라이언트 구성

Claude Desktop (STDIO)

{
  "mcpServers": {
    "google-photos": {
      "command": "node",
      "args": ["/path/to/google-photos-mcp/dist/index.js", "--stdio"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:3000/auth/callback"
      }
    }
  }
}

Cursor IDE

STDIO (권장):

• 유형: Command

• 명령어: node /path/to/google-photos-mcp/dist/index.js --stdio

HTTP:

• 유형: URL

• URL: http://localhost:3000/mcp

Smithery

# Claude Desktop
npx -y @smithery/cli install google-photos-mcp --client claude

# Cursor IDE
npx -y @smithery/cli install google-photos-mcp --client cursor

MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js        # HTTP
npx @modelcontextprotocol/inspector node dist/index.js --stdio # STDIO

사용 가능한 도구 (19)

검색 및 탐색

쓰기 및 관리

Picker API

인증

예시 쿼리

"Show me photos from my trip to Paris"
"Find photos of my dog from 2024"
"List my photo albums"
"Upload these vacation photos to a new album called 'Summer 2025'"
"Search for landscape photos from last year, ordered newest first"
"Let me pick some photos from my library" (triggers Picker API)

위치 데이터

위치 데이터는 OpenStreetMap/Nominatim 지오코딩을 사용하여 사진 설명에서 추출된 근사치입니다. 사용 가능한 경우 위도/경도, 도시, 지역, 국가 정보가 포함됩니다.

배포 / 릴리스

이 프로젝트는 Claude Desktop이나 Cursor와 같은 AI 클라이언트와 함께 로컬에서 실행하기 위한 MCP(Model Context Protocol) 서버입니다. 로컬 체크아웃 또는 NPM 설치를 최신 상태로 유지하는 것 외에 별도의 원격 배포나 릴리스 프로세스는 필요하지 않습니다.

문제 해결

• Node 버전: 이전 버전은 지원되지 않으므로 Node.js 22.22 이상을 사용하고 있는지 확인하십시오.

• 인증: GOOGLE_CLIENT_ID is not set 오류가 발생하거나 인증에 실패하면, 루트 디렉토리에 .env 파일이 있고 올바른 Google Cloud 자격 증명이 포함되어 있는지 확인하십시오. STDIO 모드로 전환하기 전에 npm start(HTTP 모드)를 실행하여 인증하는 것을 잊지 마십시오.

• 할당량 문제: Google 포토 API 제한이 적용됩니다. 일일 10,000회 요청 제한을 초과하지 않는지 확인하십시오. 서버는 quotaManager를 통해 이를 추적합니다.

• CORS 오류: 서버는 드라이브 바이 공격을 방지하기 위해 의도적으로 CORS를 비활성화합니다. 브라우저 AJAX 요청에서 서버를 직접 호출하지 마십시오.

개발

프로젝트 구조

src/
├── index.ts              # HTTP entry point
├── dxt-server.ts         # STDIO/DXT entry point
├── mcp/core.ts           # All tool handlers (19 tools)
├── api/
│   ├── client.ts         # REST client (Library + Picker)
│   ├── photos.ts         # Facade module (re-exports)
│   ├── types.ts          # TypeScript interfaces
│   └── repositories/     # Low-level API calls
├── auth/                 # OAuth, tokens, keychain
├── schemas/              # Zod validation schemas
├── utils/                # Config, logging, quota, retry
└── views/                # HTML templates

테스트

npm test              # All tests (Vitest)
npm run test:watch    # Interactive TDD
npm run test:coverage # Coverage report
npm run test:security # Security suite only

품질 검사

병합 전 다음 세 가지를 모두 통과해야 합니다:

npx tsc --noEmit   # Type check
npm run lint        # ESLint
npm test            # Tests

라이선스

MIT