google-workspace-mcp

🔧 Google Workspace MCP Server

🇮🇹 Italiano | 🇬🇧 English

---

Italiano

Server MCP (Model Context Protocol) per gestire Google Workspace tramite Claude AI e altri assistenti compatibili. Permette di amministrare utenti, gruppi, alias e unità organizzative tramite conversazione naturale.

✨ Funzionalità

Tool	Descrizione
gw_list_users	Lista utenti con ricerca e filtri
gw_get_user	Dettaglio completo di un utente
gw_create_user	Crea nuovo utente con password auto-generata
gw_delete_user	Elimina utente (con conferma obbligatoria)
gw_suspend_user	Sospendi o riattiva un utente
gw_reset_password	Reset password con generazione automatica
gw_manage_alias	Aggiungi, rimuovi, elenca alias email
gw_list_groups	Lista gruppi del dominio o di un utente
gw_manage_group_member	Aggiungi/rimuovi membri dai gruppi
gw_list_org_units	Lista unità organizzative
gw_move_user_org	Sposta utente tra unità organizzative

📋 Prerequisiti

• Python 3.10+
• Account Google Workspace con accesso admin
• Progetto Google Cloud con Admin SDK API abilitata
• Claude Desktop o altro client MCP

🚀 Installazione

pip install google-workspace-mcp

Oppure da sorgente:

git clone https://github.com/aringad/google-workspace-mcp.git
cd google-workspace-mcp
pip install -r requirements.txt

🔑 Configurazione Google Cloud

1. Crea progetto e abilita API

1. Vai su console.cloud.google.com
2. Crea un nuovo progetto (o usa quello esistente)
3. Vai su API e servizi → Libreria
4. Cerca e abilita: Admin SDK API

2. Crea Service Account

1. Vai su API e servizi → Credenziali
2. Crea credenziali → Account di servizio
3. Dai un nome (es. mcp-workspace-admin)
4. Vai nel Service Account → Chiavi → Aggiungi chiave → JSON
5. Scarica il file JSON (queste sono le tue credenziali)
6. Annota il Client ID (numero lungo nei dettagli del Service Account)

⚠️ Non serve assegnare ruoli IAM al Service Account. I permessi vengono dalla delega domain-wide.

3. Delega Domain-Wide

1. Vai su admin.google.com
2. Sicurezza → Accesso e controllo dati → Controlli API → Gestisci delega a livello di dominio
3. Clicca Aggiungi nuovo
4. Inserisci il Client ID del Service Account
5. Come ambiti OAuth, inserisci:

https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.group,https://www.googleapis.com/auth/admin.directory.orgunit,https://www.googleapis.com/auth/admin.directory.user.alias

6. Autorizza

⚙️ Variabili d'ambiente

Variabile	Descrizione	Default
GOOGLE_SERVICE_ACCOUNT_FILE	Path al file JSON delle credenziali	./credentials.json
GOOGLE_ADMIN_EMAIL	Email del super admin con delega	(obbligatorio)
GOOGLE_CUSTOMER_ID	Customer ID del dominio	my_customer

🔌 Configurazione Claude Desktop

Aggiungi al file di configurazione:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google_workspace": {
      "command": "/percorso/completo/google-workspace-mcp/venv/bin/python",
      "args": ["/percorso/completo/google-workspace-mcp/server.py"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_FILE": "/percorso/completo/credentials.json",
        "GOOGLE_ADMIN_EMAIL": "[email protected]"
      }
    }
  }
}

Chiudi completamente Claude Desktop (Cmd+Q su Mac) e riaprilo.

🏢 Configurazione multi-cliente

Puoi gestire più domini aggiungendo istanze separate:

{
  "mcpServers": {
    "gw_cliente_alfa": {
      "command": "/percorso/venv/bin/python",
      "args": ["server.py"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_FILE": "/percorso/credentials-alfa.json",
        "GOOGLE_ADMIN_EMAIL": "[email protected]"
      }
    },
    "gw_cliente_beta": {
      "command": "/percorso/venv/bin/python",
      "args": ["server.py"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_FILE": "/percorso/credentials-beta.json",
        "GOOGLE_ADMIN_EMAIL": "[email protected]"
      }
    }
  }
}

💬 Esempi d'uso

Una volta configurato, puoi dire a Claude:

• "Mostrami tutti gli utenti del dominio"
• "Crea un nuovo utente [email protected], nome Mario Rossi"
• "Sospendi l'utente [email protected]"
• "Resetta la password di [email protected]"
• "Aggiungi l'alias [email protected] all'utente [email protected]"
• "Aggiungi [email protected] al gruppo [email protected]"
• "In che unità organizzative è diviso il dominio?"

Puoi anche copiare direttamente l'email del cliente con la richiesta e Claude interpreterà automaticamente le operazioni da eseguire.

🔒 Sicurezza

• Le credenziali del Service Account non vanno mai committate nel repository
• Le password temporanee generate sono di 16 caratteri con lettere, numeri e simboli
• Le operazioni distruttive (eliminazione) richiedono conferma esplicita
• Il Service Account opera con i soli permessi strettamente necessari
• Nessun dato viene memorizzato dal server MCP

🧪 Test

# Verifica che il server parta
python server.py --help

# Test con MCP Inspector
npx @modelcontextprotocol/inspector python server.py

---

English

MCP (Model Context Protocol) Server to integrate Google Workspace Admin with Claude AI and other compatible assistants. Manage users, groups, aliases and organizational units through natural conversation.

✨ Features

Tool	Description
gw_list_users	List users with search and filters
gw_get_user	Full user details
gw_create_user	Create new user with auto-generated password
gw_delete_user	Delete user (requires explicit confirmation)
gw_suspend_user	Suspend or reactivate a user
gw_reset_password	Reset password with automatic generation
gw_manage_alias	Add, remove, list email aliases
gw_list_groups	List domain or user groups
gw_manage_group_member	Add/remove group members
gw_list_org_units	List organizational units
gw_move_user_org	Move user between organizational units

📋 Prerequisites

• Python 3.10+
• Google Workspace account with admin access
• Google Cloud project with Admin SDK API enabled
• Claude Desktop or another MCP client

🚀 Installation

pip install google-workspace-mcp

Or from source:

git clone https://github.com/aringad/google-workspace-mcp.git
cd google-workspace-mcp
pip install -r requirements.txt

🔑 Google Cloud Setup

1. Create project and enable API

1. Go to console.cloud.google.com
2. Create a new project (or use existing one)
3. Go to APIs & Services → Library
4. Search and enable: Admin SDK API

2. Create Service Account

1. Go to APIs & Services → Credentials
2. Create Credentials → Service Account
3. Name it (e.g., mcp-workspace-admin)
4. Go to the Service Account → Keys → Add Key → JSON
5. Download the JSON file (these are your credentials)
6. Note the Client ID (long number in Service Account details)

⚠️ No IAM roles needed on the Service Account. Permissions come from domain-wide delegation.

3. Domain-Wide Delegation

1. Go to admin.google.com
2. Security → Access and data control → API controls → Manage Domain Wide Delegation
3. Click Add new
4. Enter the Service Account Client ID
5. For OAuth scopes, enter:

https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.group,https://www.googleapis.com/auth/admin.directory.orgunit,https://www.googleapis.com/auth/admin.directory.user.alias

6. Authorize

⚙️ Environment Variables

Variable	Description	Default
GOOGLE_SERVICE_ACCOUNT_FILE	Path to credentials JSON file	./credentials.json
GOOGLE_ADMIN_EMAIL	Super admin email with delegation	(required)
GOOGLE_CUSTOMER_ID	Domain customer ID	my_customer

🔌 Claude Desktop Configuration

Add to config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google_workspace": {
      "command": "/full/path/to/google-workspace-mcp/venv/bin/python",
      "args": ["/full/path/to/google-workspace-mcp/server.py"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_FILE": "/full/path/to/credentials.json",
        "GOOGLE_ADMIN_EMAIL": "[email protected]"
      }
    }
  }
}

Fully quit Claude Desktop (Cmd+Q on Mac) and reopen it.

💬 Usage Examples

Once configured, you can tell Claude:

• "Show me all domain users"
• "Create a new user [email protected], name John Doe"
• "Suspend user [email protected]"
• "Reset the password for [email protected]"
• "Add the alias [email protected] to user [email protected]"
• "Add [email protected] to the [email protected] group"
• "What organizational units does the domain have?"

You can also paste client emails with requests directly — Claude will automatically interpret the operations to perform.

🔒 Security

• Service Account credentials must never be committed to the repository
• Temporary passwords are 16 characters with letters, numbers, and symbols
• Destructive operations (deletion) require explicit confirmation
• The Service Account operates with minimum necessary permissions
• No data is stored by the MCP server

🧪 Testing

# Verify server starts
python server.py --help

# Test with MCP Inspector
npx @modelcontextprotocol/inspector python server.py

---

📄 License

MIT License — See LICENSE for details.

👨‍💻 Author

Developed by Mediaform s.c.r.l. — Genova, Italy

---

Built with MCP and Google Admin SDK