Google Photos

Acesse e gerencie sua biblioteca do Google Photos com assistentes de IA.

Documentação

Servidor MCP do Google Photos

Um servidor Model Context Protocol (MCP) para integração com o Google Photos, permitindo que Claude, Gemini e outros assistentes de IA leiam, escrevam e selecionem fotos da sua biblioteca do Google Photos.

✅ Suporte à API Picker (março de 2025+)

Este servidor implementa a API Picker do Google Photos, fornecendo acesso completo à biblioteca mesmo após a descontinuação de determinados escopos da API Library em 31 de março de 2025.

Recurso	Status	API
Navegar pela biblioteca completa de fotos	✅	Picker API
Pesquisar fotos por texto/data/categoria	✅	Library API
Criar álbuns e enviar fotos	✅	Library API
Acessar conteúdo criado por aplicativos	✅	Library API

Como funciona a API Picker

Chame create_picker_session — retorna uma URL que o usuário abre no navegador
O usuário seleciona fotos da biblioteca completa
Chame poll_picker_session — quando mediaItemsSet for verdadeiro, as fotos selecionadas são retornadas

🛡️ Aviso de Segurança: CORS Removido

O middleware CORS foi removido por segurança (evita ataques drive-by em localhost).

✅ Modo STDIO (Claude Desktop): Funciona normalmente
✅ HTTP Streamable (Cursor, servidor a servidor): Funciona normalmente
❌ AJAX no navegador: Não suportado (por design)

Recursos

Operações de leitura

Pesquisar fotos por texto, data, localização, categoria, favoritos
Filtrar por tipo de mídia (foto/vídeo), intervalos de datas, status de arquivamento
Obter detalhes das fotos, incluindo imagens codificadas em base64
Listar álbuns e seus conteúdos
Descrever os recursos de filtro disponíveis

Operações de escrita

Criar álbuns e enviar fotos
Envio em lote com create_album_with_media (até 50 arquivos)
Adicionar enriquecimentos de texto e localização aos álbuns
Definir fotos de capa dos álbuns

Operações do Picker

Criar sessões do Picker para acesso completo à biblioteca
Consultar sessões e recuperar itens de mídia selecionados

Infraestrutura

⚡ Transporte HTTP Streamable (especificação MCP 2025-06-18)
🔗 HTTPS Keep-Alive com pooling de conexões
🔒 Armazenamento de tokens no chaveiro do sistema operacional
📊 Gerenciamento de cota com rastreamento automático
🔄 Atualização automática de tokens

Pré-requisitos

Node.js 22.22+
Projeto no Google Cloud com a API Photos Library habilitada
Credenciais OAuth 2.0 (tipo Aplicativo Web)

Configuração

1. Configuração do Google Cloud

Acesse o Console do Google Cloud
Crie um novo projeto (ou selecione um existente)
Habilite a API Photos Library
Crie credenciais OAuth 2.0 (Aplicativo Web)
Adicione http://localhost:3000/auth/callback como URI de redirecionamento autorizado
Anote seu Client ID e Client Secret

2. Instalação

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

3. Configuração

cp .env.example .env

Edite .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. Compilar e executar

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. Autenticar

Inicie no modo HTTP: npm start
Visite http://localhost:3000/auth no seu navegador
Conclua o fluxo OAuth do Google
Os tokens são salvos automaticamente no chaveiro do sistema operacional

Nota: A autenticação deve ser concluída primeiro no modo HTTP. Depois disso, alterne para o modo STDIO para o Claude Desktop.

Porta dinâmica

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

Configuração do cliente

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"
      }
    }
  }
}

IDE Cursor

STDIO (recomendado):

Tipo: Comando
Comando: node /path/to/google-photos-mcp/dist/index.js --stdio

HTTP:

Tipo: 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

Ferramentas disponíveis (19)

Pesquisa e navegação

Ferramenta	Descrição
`search_photos`	Pesquisa de fotos baseada em texto
`search_photos_by_location`	Pesquisa por nome de localização
`search_media_by_filter`	Filtrar por datas, categorias, tipo de mídia, favoritos, arquivados
`get_photo`	Obter detalhes da foto (base64 opcional)
`list_albums`	Listar todos os álbuns
`get_album`	Obter detalhes do álbum
`list_album_photos`	Listar fotos em um álbum
`list_media_items`	Listar todos os itens de mídia
`describe_filter_capabilities`	Referência JSON de todas as opções de filtro

Escrita e gerenciamento

Ferramenta	Descrição
`create_album`	Criar um novo álbum
`upload_media`	Enviar um arquivo local
`add_media_to_album`	Adicionar itens existentes a um álbum (máx. 50)
`create_album_with_media`	Criar álbum + enviar arquivos em uma única chamada (máx. 50)
`add_album_enrichment`	Adicionar enriquecimento de texto ou localização
`set_album_cover`	Definir foto de capa do álbum

API Picker

Ferramenta	Descrição
`create_picker_session`	Iniciar uma sessão do Picker para acesso completo à biblioteca
`poll_picker_session`	Verificar o status da sessão e recuperar fotos selecionadas

Autenticação

Ferramenta	Descrição
`auth_status`	Verificar o status da autenticação
`start_auth`	Iniciar o fluxo OAuth via servidor local temporário

Exemplos de consultas

"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)

Dados de localização

Os dados de localização são aproximados, extraídos das descrições das fotos usando geocodificação OpenStreetMap/Nominatim. Quando disponíveis, incluem latitude/longitude, cidade, região e país.

Implantação / lançamento

Este projeto é um servidor Model Context Protocol (MCP) destinado a ser executado localmente junto com clientes de IA como Claude Desktop ou Cursor. Não há processo de implantação remota ou lançamento necessário além de manter seu checkout local ou instalação NPM atualizados.

Solução de problemas

Versão do Node: Certifique-se de estar usando Node.js 22.22+, pois versões mais antigas não são suportadas.
Autenticação: Se você encontrar erros de GOOGLE_CLIENT_ID is not set ou a autenticação falhar, verifique se o arquivo .env está presente no diretório raiz e contém suas credenciais corretas do Google Cloud. Lembre-se de executar npm start (modo HTTP) para autenticar antes de alternar para o modo STDIO.
Problemas de cota: Os limites da API do Google Photos se aplicam. Certifique-se de não estar atingindo o limite de cota de 10.000 solicitações/dia. O servidor rastreia isso via quotaManager.
Erros de CORS: O servidor desabilita intencionalmente o CORS para prevenir ataques drive-by. Não tente chamar o servidor diretamente de solicitações AJAX no navegador.

Desenvolvimento

Estrutura do projeto

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

Testes

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

Verificações de qualidade

Todas as três devem passar antes do merge:

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

Licença

MIT