Google Photos MCP-Server

Ein Model Context Protocol (MCP)-Server für die Google Photos-Integration, der es Claude, Gemini und anderen KI-Assistenten ermöglicht, Fotos aus Ihrer Google Photos-Bibliothek zu lesen, zu schreiben und auszuwählen.

✅ Picker API-Unterstützung (März 2025+)

Dieser Server implementiert die Google Photos Picker API und bietet vollen Zugriff auf die Bibliothek, auch nach der Einstellung bestimmter Library API-Scopes am 31. März 2025.

Funktionsweise der Picker API

1. create_picker_session aufrufen — gibt eine URL zurück, die der Benutzer in seinem Browser öffnet

2. Der Benutzer wählt Fotos aus seiner gesamten Bibliothek aus

3. poll_picker_session aufrufen — sobald mediaItemsSet wahr ist, werden die ausgewählten Fotos zurückgegeben

Related MCP server: CoreViz MCP

🛡️ Sicherheitshinweis: CORS entfernt

Die CORS-Middleware wurde aus Sicherheitsgründen entfernt (verhindert Drive-by-Angriffe auf localhost).

• ✅ STDIO-Modus (Claude Desktop): Funktioniert normal

• ✅ Streamable HTTP (Cursor, Server-zu-Server): Funktioniert normal

• ❌ Browser AJAX: Nicht unterstützt (beabsichtigt)

Funktionen

Leseoperationen

• Suche nach Fotos nach Text, Datum, Standort, Kategorie, Favoriten

• Filtern nach Medientyp (Foto/Video), Datumsbereichen, Archivstatus

• Abrufen von Fotodetails einschließlich base64-kodierter Bilder

• Auflisten von Alben und deren Inhalten

• Beschreibung der verfügbaren Filterfunktionen

Schreiboperationen

• Alben erstellen und Fotos hochladen

• Batch-Upload mit create_album_with_media (bis zu 50 Dateien)

• Hinzufügen von Text- und Standortanreicherungen zu Alben

• Festlegen von Album-Coverfotos

Picker-Operationen

• Erstellen von Picker-Sitzungen für den Zugriff auf die gesamte Bibliothek

• Abfragen von Sitzungen und Abrufen ausgewählter Medienelemente

Infrastruktur

• ⚡ Streamable HTTP-Transport (MCP 2025-06-18 Spezifikation)

• 🔗 HTTPS Keep-Alive mit Verbindungspooling

• 🔒 OS-Keychain-Token-Speicherung

• 📊 Kontingentverwaltung mit automatischer Nachverfolgung

• 🔄 Automatische Token-Aktualisierung

Voraussetzungen

• Node.js 22.22+

• Google Cloud-Projekt mit aktivierter Photos Library API

• OAuth 2.0-Anmeldedaten (Typ Webanwendung)

Einrichtung

1. Google Cloud-Einrichtung

1. Gehen Sie zur Google Cloud Console

2. Erstellen Sie ein neues Projekt (oder wählen Sie ein bestehendes aus)

3. Aktivieren Sie die Photos Library API

4. Erstellen Sie OAuth 2.0-Anmeldedaten (Webanwendung)

5. Fügen Sie http://localhost:3000/auth/callback als autorisierte Weiterleitungs-URI hinzu

6. Notieren Sie sich Ihre Client-ID und Ihr Client-Geheimnis

2. Installation

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

3. Konfiguration

cp .env.example .env

Bearbeiten Sie .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. Build & Ausführen

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

1. Starten Sie im HTTP-Modus: npm start

2. Besuchen Sie http://localhost:3000/auth in Ihrem Browser

3. Schließen Sie den Google OAuth-Prozess ab

4. Token werden automatisch im OS-Keychain gespeichert

Hinweis: Die Authentifizierung muss zuerst im HTTP-Modus abgeschlossen werden. Wechseln Sie danach für Claude Desktop in den STDIO-Modus.

Dynamischer Port

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

Client-Konfiguration

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 (empfohlen):

• Typ: Befehl

• Befehl: node /path/to/google-photos-mcp/dist/index.js --stdio

HTTP:

• Typ: 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

Verfügbare Tools (19)

Suchen & Durchsuchen

Schreiben & Verwalten

Picker API

Auth

Beispielabfragen

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

Standortdaten

Standortdaten sind ungefähre Angaben, die aus Fotobeschreibungen mittels OpenStreetMap/Nominatim-Geocodierung extrahiert wurden. Falls verfügbar, enthalten sie Breitengrad/Längengrad, Stadt, Region, Land.

Bereitstellung / Release

Dieses Projekt ist ein Model Context Protocol (MCP)-Server, der lokal neben KI-Clients wie Claude Desktop oder Cursor ausgeführt werden soll. Es ist kein Remote-Deployment oder Release-Prozess erforderlich, außer Ihren lokalen Checkout oder die NPM-Installation auf dem neuesten Stand zu halten.

Fehlerbehebung

• Node-Version: Stellen Sie sicher, dass Sie Node.js 22.22+ verwenden, da ältere Versionen nicht unterstützt werden.

• Authentifizierung: Wenn Fehler wie GOOGLE_CLIENT_ID is not set auftreten oder die Authentifizierung fehlschlägt, überprüfen Sie, ob Ihre .env-Datei im Stammverzeichnis vorhanden ist und Ihre korrekten Google Cloud-Anmeldedaten enthält. Denken Sie daran, npm start (HTTP-Modus) auszuführen, um sich zu authentifizieren, bevor Sie in den STDIO-Modus wechseln.

• Kontingentprobleme: Es gelten die Limits der Google Photos API. Stellen Sie sicher, dass Sie das Kontingent von 10.000 Anfragen pro Tag nicht überschreiten. Der Server verfolgt dies über quotaManager.

• CORS-Fehler: Der Server deaktiviert absichtlich CORS, um Drive-by-Angriffe zu verhindern. Versuchen Sie nicht, den Server direkt über Browser-AJAX-Anfragen aufzurufen.

Entwicklung

Projektstruktur

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

Testen

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

Qualitätsprüfungen

Alle drei müssen vor dem Zusammenführen (Merge) bestanden werden:

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

Lizenz

MIT