Gmail MCP Server

Serveur MCP pour Gmail. En lecture seule par défaut ; l'envoi de mails peut être activé explicitement via ENABLE_WRITE=true. La suppression de messages n'est jamais exposée.

Outils disponibles

Related MCP server: Gmail MCP Server

Prérequis

• Bun installé

• Un compte Google Cloud (gratuit)

Installation et configuration

1. Installer les dépendances

bun install

2. Créer le projet Google Cloud et les credentials

Suivez ces étapes dans la Google Cloud Console :

Créer un projet

1. Ouvrez console.cloud.google.com

2. Cliquez sur le menu déroulant de sélection de projet dans la barre du haut (à côté du logo Google Cloud)

3. Cliquez sur "New Project"

4. Saisissez un nom (ex: Gmail MCP Server) → cliquez "Create"

5. Attendez la notification de création, puis sélectionnez le projet créé dans le même menu

Activer l'API Gmail

1. Menu latéral gauche → "APIs & Services" → "Library"

2. Dans la barre de recherche, tapez Gmail API

3. Cliquez sur "Gmail API" dans les résultats

4. Cliquez sur le bouton bleu "Enable"

Configurer l'écran de consentement OAuth

1. Menu latéral → "APIs & Services" → "OAuth consent screen"

2. Type d'utilisateur : sélectionnez "External" → cliquez "Create"

3. Remplissez les champs obligatoires :

   • App name : Gmail MCP Server (ou ce que vous voulez)

   • User support email : votre adresse email

   • Developer contact information > Email addresses : votre adresse email

4. Cliquez "Save and Continue"

5. Sur la page "Scopes" :

   • Cliquez "Add or Remove Scopes"

   • Dans le filtre de recherche, tapez gmail.readonly

   • Cochez ".../auth/gmail.readonly" (libellé : "Read all resources and their metadata—no write operations")

   • Tapez ensuite gmail.send dans le filtre

   • Cochez ".../auth/gmail.send" (libellé : "Send email on your behalf")

   • Cliquez "Update" puis "Save and Continue"

6. Sur la page "Test users" :

   • Cliquez "+ Add Users"

   • Entrez votre adresse Gmail (celle que vous souhaitez utiliser)

   • Cliquez "Add" puis "Save and Continue"

7. Sur le récapitulatif, cliquez "Back to Dashboard"

Pourquoi gmail.send dès le départ ? Le script de setup demande les deux scopes en une seule autorisation. Cela évite de relancer toute la procédure si vous activez ENABLE_WRITE=true plus tard. Le scope gmail.send ne sera exploité que si ENABLE_WRITE=true est présent dans .env.

Créer les identifiants OAuth 2.0

1. Menu latéral → "APIs & Services" → "Credentials"

2. Cliquez "+ Create Credentials" → "OAuth client ID"

3. Application type : sélectionnez "Desktop app"

4. Name : laissez la valeur par défaut ou saisissez Gmail MCP

5. Cliquez "Create"

6. Une fenêtre s'affiche avec vos credentials :

   • Your Client ID → c'est votre GMAIL_CLIENT_ID

   • Your Client Secret → c'est votre GMAIL_CLIENT_SECRET

7. Notez ces deux valeurs (ou téléchargez le JSON via "Download JSON"), puis cliquez "OK"

3. Lancer le script de configuration

bun run setup

Ce script interactif va :

• Vous demander de coller le Client ID et le Client Secret

• Ouvrir un serveur local sur le port 1975 pour recevoir le callback OAuth

• Vous afficher une URL à ouvrir dans votre navigateur

• Après autorisation, récupérer automatiquement le refresh_token

• Créer le fichier .env avec toutes les variables (dont ENABLE_WRITE=false par défaut)

Note : Pendant l'autorisation Google, si vous voyez "Google hasn't verified this app", cliquez sur "Advanced" puis "Go to [nom de l'app] (unsafe)". C'est normal pour une application en mode test.

Activer l'envoi de mails

Par défaut, le serveur est en lecture seule. Pour activer l'outil send_message :

1. Ouvrez le fichier .env à la racine du projet

2. Changez la ligne ENABLE_WRITE=false en :

ENABLE_WRITE=true

3. Redémarrez le serveur — l'outil send_message apparaîtra dans tools/list

Important : si votre refresh token existant date d'avant l'ajout du scope gmail.send dans votre écran de consentement OAuth, vous devrez relancer bun run setup pour obtenir un nouveau token avec ce scope.

Ajouter gmail.send à un projet Google Cloud existant

Si vous avez déjà configuré le projet Google Cloud sans cocher gmail.send lors de l'étape "Scopes" :

1. Menu latéral → "APIs & Services" → "OAuth consent screen"

2. Cliquez sur "Edit App"

3. Avancez jusqu'à l'étape "Scopes" → cliquez "Add or Remove Scopes"

4. Dans le filtre, tapez gmail.send

5. Cochez ".../auth/gmail.send"

6. Cliquez "Update" → "Save and Continue" jusqu'au bout

7. Relancez bun run setup pour générer un nouveau refresh token incluant ce scope

Démarrage

Mode HTTP (pour clients web / frontend)

bun run start

Le serveur écoute sur http://localhost:1976/mcp avec CORS ouvert (toute origine autorisée).

Mode STDIO (pour Claude Desktop et agents CLI)

bun run start:stdio

Vérification

# Lister les outils disponibles
curl -X POST http://localhost:1976/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Health check
curl http://localhost:1976/health

Configuration avancée

Toutes les variables sont dans .env :

GMAIL_CLIENT_ID=votre-client-id
GMAIL_CLIENT_SECRET=votre-client-secret
GMAIL_REFRESH_TOKEN=votre-refresh-token
PORT=1976
ENABLE_WRITE=false

Intégration avec Claude Desktop

Ajoutez dans votre claude_desktop_config.json :

{
  "mcpServers": {
    "gmail": {
      "command": "bun",
      "args": ["run", "/chemin/vers/gmail-mcp-server/src/server.ts", "--stdio"],
      "env": {
        "GMAIL_CLIENT_ID": "votre-client-id",
        "GMAIL_CLIENT_SECRET": "votre-client-secret",
        "GMAIL_REFRESH_TOKEN": "votre-refresh-token",
        "ENABLE_WRITE": "false"
      }
    }
  }
}

Sécurité

• Le scope OAuth gmail.readonly est toujours demandé — aucune écriture sans ENABLE_WRITE=true.

• Le scope gmail.send est inclus dans le token mais l'outil send_message n'est enregistré que si ENABLE_WRITE=true est explicitement défini dans .env.

• La suppression de messages n'est jamais exposée, quelle que soit la valeur de ENABLE_WRITE.

• Le fichier .env est exclu du git via .gitignore — ne le committez jamais.

• Le refresh_token donne un accès durable : stockez-le en lieu sûr.