✨ Overview

mcp-workspace-admin exposes Google Workspace Admin operations as MCP tools, making it trivial for AI agents and Claude Code workflows to:

• 🌐 Add & verify domains — programmatically add domains to your Workspace and retrieve the DNS verification token
• 👤 Manage mailboxes — create users, list accounts, and reset passwords
• 🔏 Set up DKIM — generate keys and inject records into DNS

Originally built for cold email infrastructure automation: buy domains → add to Workspace → create sending mailboxes → configure DNS — all in a single agent workflow, zero manual steps.

📋 Prerequisites

1. A Google Workspace account (any tier)
2. A Google Cloud project with the Admin SDK API enabled
3. A Service Account with domain-wide delegation configured
4. Python 3.11+

🚀 Setup

1. Create a Service Account

In Google Cloud Console → IAM & Admin → Service Accounts:

1. Create a new service account (e.g. workspace-admin-mcp)
2. Click the account → Keys → Add Key → JSON → download the file
3. Note the Client ID from the service account details page

2. Grant Domain-Wide Delegation

In Google Workspace Admin → Security → API controls → Domain-wide delegation:

1. Click Add new
2. Enter the service account's Client ID
3. Add these OAuth scopes:

https://www.googleapis.com/auth/admin.directory.domain,
https://www.googleapis.com/auth/admin.directory.user,
https://www.googleapis.com/auth/gmail.settings.sharing

4. Click Authorize

3. Install

git clone https://github.com/keyserfaty/mcp-workspace-admin
cd mcp-workspace-admin

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

pip install -e .

4. Configure Environment

export GOOGLE_SERVICE_ACCOUNT_JSON="/path/to/service-account-key.json"
export GOOGLE_WORKSPACE_ADMIN_EMAIL="admin@yourdomain.com"

⚙️ MCP Configuration

Add to your ~/.claude.json (or project .mcp.json):

{
  "mcpServers": {
    "workspace-admin": {
      "type": "stdio",
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/mcp-workspace-admin/server.py"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_JSON": "/path/to/service-account-key.json",
        "GOOGLE_WORKSPACE_ADMIN_EMAIL": "admin@yourdomain.com"
      }
    }
  }
}

🛠️ Tools Reference

Domain Management

| Tool | Description | Key Parameters | |------|-------------|----------------| | add_domain | Add a domain to Workspace; returns the DNS verification TXT record | domain: str | | get_domain_status | Check if a domain is verified | domain: str | | list_domains | List all domains in the account | — |

Typical domain onboarding flow:

# 1. Add domain → get verification token
result = add_domain("example.com")
# → inject result["txt_record"] into DNS at @ as TXT

# 2. Poll until verified (DNS propagation: ~1–5 min)
status = get_domain_status("example.com")
# → status["verified"] == True once propagated

User / Mailbox Management

| Tool | Description | Key Parameters | |------|-------------|----------------| | create_user | Create a new Workspace mailbox | email, first_name, last_name, password | | list_users | List users, optionally filtered by domain | domain?: str, max_results?: int | | reset_password | Reset a user's password | email, new_password, force_change?: bool |

DKIM

| Tool | Description | Key Parameters | |------|-------------|----------------| | generate_dkim_key | Generate a DKIM signing key | domain: str, key_length?: int | | get_dkim_record | Retrieve the DKIM TXT record name and Admin console link | domain: str | | enable_dkim | Instructions to activate DKIM signing | domain: str |

⚠️ DKIM limitation — see below.

⚠️ Known Limitations

DKIM cannot be fully automated via API

Google's public REST APIs do not expose DKIM key generation, retrieval, or activation endpoints. The three DKIM tools return the correct DNS record name and a direct link to the Admin console page instead of performing the action programmatically.

Manual steps required for DKIM:

Google Workspace Admin Console
  → Apps → Google Workspace → Gmail → Authenticate email
  → Select domain → Generate new record
  → Copy the TXT value → inject into DNS at google._domainkey.<domain>
  → Wait ~30–60 min for DNS propagation
  → Click "Start authentication"

PRs that automate this via browser automation (e.g. Playwright) are very welcome.

🤖 Example Agent Workflow

This server is designed to power cold email infrastructure automation. A full agent flow:

1. Purchase domain via registrar API (e.g. Porkbun)
2. add_domain("newdomain.com")                 ← workspace-admin MCP
3. Inject verification TXT into registrar DNS
4. Poll get_domain_status() until verified
5. create_user("hello@newdomain.com", ...)     ← workspace-admin MCP
6. create_user("info@newdomain.com", ...)      ← workspace-admin MCP
7. Add SPF / DMARC records via registrar API
8. DKIM setup (see limitation above)
9. Connect mailboxes to sending platform for warmup

📁 Project Structure

mcp-workspace-admin/
├── server.py          # MCP server & tool definitions
├── auth.py            # Google service account auth helpers
├── pyproject.toml     # Package metadata & dependencies
└── README.md

🤝 Contributing

Contributions welcome — especially:

• DKIM automation via Playwright/browser automation fallback
• Send-as alias management
• Group / mailing list management
• Suspend / restore user tools

git checkout -b feature/your-feature
# make changes
git commit -m "feat: describe your change"
git push origin feature/your-feature
# open a PR

📄 License

MIT © Karen Serfaty