MCP-сервер Google Photos

Сервер протокола контекста модели (MCP) для интеграции с Google Photos, позволяющий Claude, Gemini и другим ИИ-ассистентам читать, записывать и выбирать фотографии из вашей библиотеки Google Photos.

✅ Поддержка Picker API (март 2025 г. и позже)

Этот сервер реализует Google Photos Picker API, обеспечивая полный доступ к библиотеке даже после прекращения поддержки некоторых областей (scopes) Library API 31 марта 2025 года.

Как работает Picker API

1. Вызовите create_picker_session — вернется URL, который пользователь откроет в браузере

2. Пользователь выбирает фотографии из своей полной библиотеки

3. Вызовите poll_picker_session — когда mediaItemsSet станет true, выбранные фотографии будут возвращены

Related MCP server: CoreViz MCP

🛡️ Уведомление о безопасности: CORS удален

Промежуточное ПО CORS было удалено в целях безопасности (предотвращает drive-by атаки на localhost).

• ✅ Режим STDIO (Claude Desktop): работает в обычном режиме

• ✅ Streamable HTTP (Cursor, сервер-сервер): работает в обычном режиме

• ❌ Браузерный AJAX: не поддерживается (преднамеренно)

Функции

Операции чтения

• Поиск фото по тексту, дате, местоположению, категории, избранному

• Фильтрация по типу медиа (фото/видео), диапазонам дат, статусу архивации

• Получение сведений о фото, включая изображения в формате base64

• Список альбомов и их содержимого

• Описание доступных возможностей фильтрации

Операции записи

• Создание альбомов и загрузка фото

• Пакетная загрузка с помощью create_album_with_media (до 50 файлов)

• Добавление текстовых и гео-данных в альбомы

• Установка обложек альбомов

Операции Picker

• Создание сессий выбора для доступа к полной библиотеке

• Опрос сессий и получение выбранных медиа-элементов

Инфраструктура

• ⚡ Потоковый HTTP-транспорт (спецификация MCP 2025-06-18)

• 🔗 HTTPS Keep-Alive с пулом соединений

• 🔒 Хранение токенов в связке ключей ОС

• 📊 Управление квотами с автоматическим отслеживанием

• 🔄 Автоматическое обновление токенов

Предварительные требования

• Node.js 22.22+

• Проект Google Cloud с включенным Photos Library API

• Учетные данные 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. Запишите свой Client ID и Client Secret

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. Токены автоматически сохраняются в связке ключей ОС

Примечание: Аутентификация должна быть сначала завершена в режиме HTTP. После этого переключитесь в режим STDIO для Claude Desktop.

Динамический порт

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. При наличии включают широту/долготу, город, регион, страну.

Развертывание / релиз

Этот проект является сервером протокола контекста модели (MCP), предназначенным для локального запуска вместе с ИИ-клиентами, такими как Claude Desktop или Cursor. Удаленное развертывание или процесс релиза не требуются, кроме поддержания актуальности вашей локальной копии или установки NPM.

Устранение неполадок

• Версия Node: Убедитесь, что вы используете Node.js 22.22+, так как более старые версии не поддерживаются.

• Аутентификация: Если вы столкнулись с ошибками GOOGLE_CLIENT_ID is not set или аутентификация не удалась, проверьте наличие файла .env в корневом каталоге и правильность учетных данных Google Cloud. Не забудьте запустить npm start (режим HTTP) для аутентификации перед переключением в режим STDIO.

• Проблемы с квотами: Применяются ограничения API Google Photos. Убедитесь, что вы не превышаете лимит в 10 000 запросов в день. Сервер отслеживает это через quotaManager.

• Ошибки CORS: Сервер намеренно отключает CORS для предотвращения drive-by атак. Не пытайтесь вызывать сервер напрямую из 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