{
  "markdown": "# 🔧 Google Workspace MCP Server\n\n<!-- mcp-name: io.github.aringad/google-workspace-mcp -->\n\n🇮🇹 Italiano | [🇬🇧 English](#english)\n\n---\n\n## Italiano\n\nServer 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.\n\n### ✨ Funzionalità\n\n| Tool | Descrizione |\n|------|-------------|\n| `gw_list_users` | Lista utenti con ricerca e filtri |\n| `gw_get_user` | Dettaglio completo di un utente |\n| `gw_create_user` | Crea nuovo utente con password auto-generata |\n| `gw_delete_user` | Elimina utente (con conferma obbligatoria) |\n| `gw_suspend_user` | Sospendi o riattiva un utente |\n| `gw_reset_password` | Reset password con generazione automatica |\n| `gw_manage_alias` | Aggiungi, rimuovi, elenca alias email |\n| `gw_list_groups` | Lista gruppi del dominio o di un utente |\n| `gw_manage_group_member` | Aggiungi/rimuovi membri dai gruppi |\n| `gw_list_org_units` | Lista unità organizzative |\n| `gw_move_user_org` | Sposta utente tra unità organizzative |\n\n### 📋 Prerequisiti\n\n- Python 3.10+\n- Account Google Workspace con accesso admin\n- Progetto Google Cloud con Admin SDK API abilitata\n- Claude Desktop o altro client MCP\n\n### 🚀 Installazione\n\n```bash\npip install google-workspace-mcp\n```\n\nOppure da sorgente:\n\n```bash\ngit clone https://github.com/aringad/google-workspace-mcp.git\ncd google-workspace-mcp\npip install -r requirements.txt\n```\n\n### 🔑 Configurazione Google Cloud\n\n#### 1. Crea progetto e abilita API\n\n1. Vai su [console.cloud.google.com](https://console.cloud.google.com)\n2. Crea un nuovo progetto (o usa quello esistente)\n3. Vai su **API e servizi → Libreria**\n4. Cerca e abilita: **Admin SDK API**\n\n#### 2. Crea Service Account\n\n1. Vai su **API e servizi → Credenziali**\n2. **Crea credenziali → Account di servizio**\n3. Dai un nome (es. `mcp-workspace-admin`)\n4. Vai nel Service Account → **Chiavi → Aggiungi chiave → JSON**\n5. Scarica il file JSON (queste sono le tue credenziali)\n6. **Annota il Client ID** (numero lungo nei dettagli del Service Account)\n\n> ⚠️ Non serve assegnare ruoli IAM al Service Account. I permessi vengono dalla delega domain-wide.\n\n#### 3. Delega Domain-Wide\n\n1. Vai su [admin.google.com](https://admin.google.com)\n2. **Sicurezza → Accesso e controllo dati → Controlli API → Gestisci delega a livello di dominio**\n3. Clicca **Aggiungi nuovo**\n4. Inserisci il **Client ID** del Service Account\n5. Come ambiti OAuth, inserisci:\n\n```\nhttps://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\n```\n\n6. **Autorizza**\n\n### ⚙️ Variabili d'ambiente\n\n| Variabile | Descrizione | Default |\n|-----------|-------------|---------|\n| `GOOGLE_SERVICE_ACCOUNT_FILE` | Path al file JSON delle credenziali | `./credentials.json` |\n| `GOOGLE_ADMIN_EMAIL` | Email del super admin con delega | *(obbligatorio)* |\n| `GOOGLE_CUSTOMER_ID` | Customer ID del dominio | `my_customer` |\n\n### 🔌 Configurazione Claude Desktop\n\nAggiungi al file di configurazione:\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"google_workspace\": {\n      \"command\": \"/percorso/completo/google-workspace-mcp/venv/bin/python\",\n      \"args\": [\"/percorso/completo/google-workspace-mcp/server.py\"],\n      \"env\": {\n        \"GOOGLE_SERVICE_ACCOUNT_FILE\": \"/percorso/completo/credentials.json\",\n        \"GOOGLE_ADMIN_EMAIL\": \"admin@tuodominio.it\"\n      }\n    }\n  }\n}\n```\n\nChiudi completamente Claude Desktop (Cmd+Q su Mac) e riaprilo.\n\n#### 🏢 Configurazione multi-cliente\n\nPuoi gestire più domini aggiungendo istanze separate:\n\n```json\n{\n  \"mcpServers\": {\n    \"gw_cliente_alfa\": {\n      \"command\": \"/percorso/venv/bin/python\",\n      \"args\": [\"server.py\"],\n      \"env\": {\n        \"GOOGLE_SERVICE_ACCOUNT_FILE\": \"/percorso/credentials-alfa.json\",\n        \"GOOGLE_ADMIN_EMAIL\": \"admin@alfa.it\"\n      }\n    },\n    \"gw_cliente_beta\": {\n      \"command\": \"/percorso/venv/bin/python\",\n      \"args\": [\"server.py\"],\n      \"env\": {\n        \"GOOGLE_SERVICE_ACCOUNT_FILE\": \"/percorso/credentials-beta.json\",\n        \"GOOGLE_ADMIN_EMAIL\": \"admin@beta.it\"\n      }\n    }\n  }\n}\n```\n\n### 💬 Esempi d'uso\n\nUna volta configurato, puoi dire a Claude:\n\n- *\"Mostrami tutti gli utenti del dominio\"*\n- *\"Crea un nuovo utente mario.rossi@dominio.it, nome Mario Rossi\"*\n- *\"Sospendi l'utente luigi@dominio.it\"*\n- *\"Resetta la password di marco@dominio.it\"*\n- *\"Aggiungi l'alias info@dominio.it all'utente segreteria@dominio.it\"*\n- *\"Aggiungi mario@dominio.it al gruppo vendite@dominio.it\"*\n- *\"In che unità organizzative è diviso il dominio?\"*\n\nPuoi anche copiare direttamente l'email del cliente con la richiesta e Claude interpreterà automaticamente le operazioni da eseguire.\n\n### 🔒 Sicurezza\n\n- Le credenziali del Service Account **non vanno mai committate** nel repository\n- Le password temporanee generate sono di 16 caratteri con lettere, numeri e simboli\n- Le operazioni distruttive (eliminazione) richiedono conferma esplicita\n- Il Service Account opera con i soli permessi strettamente necessari\n- Nessun dato viene memorizzato dal server MCP\n\n### 🧪 Test\n\n```bash\n# Verifica che il server parta\npython server.py --help\n\n# Test con MCP Inspector\nnpx @modelcontextprotocol/inspector python server.py\n```\n\n---\n\n## English\n\n<a name=\"english\"></a>\n\nMCP (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.\n\n### ✨ Features\n\n| Tool | Description |\n|------|-------------|\n| `gw_list_users` | List users with search and filters |\n| `gw_get_user` | Full user details |\n| `gw_create_user` | Create new user with auto-generated password |\n| `gw_delete_user` | Delete user (requires explicit confirmation) |\n| `gw_suspend_user` | Suspend or reactivate a user |\n| `gw_reset_password` | Reset password with automatic generation |\n| `gw_manage_alias` | Add, remove, list email aliases |\n| `gw_list_groups` | List domain or user groups |\n| `gw_manage_group_member` | Add/remove group members |\n| `gw_list_org_units` | List organizational units |\n| `gw_move_user_org` | Move user between organizational units |\n\n### 📋 Prerequisites\n\n- Python 3.10+\n- Google Workspace account with admin access\n- Google Cloud project with Admin SDK API enabled\n- Claude Desktop or another MCP client\n\n### 🚀 Installation\n\n```bash\npip install google-workspace-mcp\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/aringad/google-workspace-mcp.git\ncd google-workspace-mcp\npip install -r requirements.txt\n```\n\n### 🔑 Google Cloud Setup\n\n#### 1. Create project and enable API\n\n1. Go to [console.cloud.google.com](https://console.cloud.google.com)\n2. Create a new project (or use existing one)\n3. Go to **APIs & Services → Library**\n4. Search and enable: **Admin SDK API**\n\n#### 2. Create Service Account\n\n1. Go to **APIs & Services → Credentials**\n2. **Create Credentials → Service Account**\n3. Name it (e.g., `mcp-workspace-admin`)\n4. Go to the Service Account → **Keys → Add Key → JSON**\n5. Download the JSON file (these are your credentials)\n6. **Note the Client ID** (long number in Service Account details)\n\n> ⚠️ No IAM roles needed on the Service Account. Permissions come from domain-wide delegation.\n\n#### 3. Domain-Wide Delegation\n\n1. Go to [admin.google.com](https://admin.google.com)\n2. **Security → Access and data control → API controls → Manage Domain Wide Delegation**\n3. Click **Add new**\n4. Enter the Service Account **Client ID**\n5. For OAuth scopes, enter:\n\n```\nhttps://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\n```\n\n6. **Authorize**\n\n### ⚙️ Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `GOOGLE_SERVICE_ACCOUNT_FILE` | Path to credentials JSON file | `./credentials.json` |\n| `GOOGLE_ADMIN_EMAIL` | Super admin email with delegation | *(required)* |\n| `GOOGLE_CUSTOMER_ID` | Domain customer ID | `my_customer` |\n\n### 🔌 Claude Desktop Configuration\n\nAdd to config file:\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"google_workspace\": {\n      \"command\": \"/full/path/to/google-workspace-mcp/venv/bin/python\",\n      \"args\": [\"/full/path/to/google-workspace-mcp/server.py\"],\n      \"env\": {\n        \"GOOGLE_SERVICE_ACCOUNT_FILE\": \"/full/path/to/credentials.json\",\n        \"GOOGLE_ADMIN_EMAIL\": \"admin@yourdomain.com\"\n      }\n    }\n  }\n}\n```\n\nFully quit Claude Desktop (Cmd+Q on Mac) and reopen it.\n\n### 💬 Usage Examples\n\nOnce configured, you can tell Claude:\n\n- *\"Show me all domain users\"*\n- *\"Create a new user john.doe@domain.com, name John Doe\"*\n- *\"Suspend user jane@domain.com\"*\n- *\"Reset the password for mark@domain.com\"*\n- *\"Add the alias info@domain.com to user secretary@domain.com\"*\n- *\"Add john@domain.com to the sales@domain.com group\"*\n- *\"What organizational units does the domain have?\"*\n\nYou can also paste client emails with requests directly — Claude will automatically interpret the operations to perform.\n\n### 🔒 Security\n\n- Service Account credentials must **never be committed** to the repository\n- Temporary passwords are 16 characters with letters, numbers, and symbols\n- Destructive operations (deletion) require explicit confirmation\n- The Service Account operates with minimum necessary permissions\n- No data is stored by the MCP server\n\n### 🧪 Testing\n\n```bash\n# Verify server starts\npython server.py --help\n\n# Test with MCP Inspector\nnpx @modelcontextprotocol/inspector python server.py\n```\n\n---\n\n## 📄 License\n\nMIT License — See [LICENSE](LICENSE) for details.\n\n## 👨‍💻 Author\n\nDeveloped by **[Mediaform s.c.r.l.](https://www.media-form.it)** — Genova, Italy\n\n---\n\n*Built with [MCP](https://modelcontextprotocol.io) and [Google Admin SDK](https://developers.google.com/admin-sdk)*\n",
  "bytes": 10329,
  "sha": "e832b2163c5b4ab19b5ab8b85bae852173b6f5079d3c7d67c4765c2faa38bf54",
  "repo_slug": "aringad/google-workspace-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aringad_google_workspace_mcp_4a1eeae5/readme"
}