Google Workspace Alias MCP

A Model Context Protocol (MCP) server for Google Workspace integration with send-as alias support, email templates, and scheduled send. This server enables AI assistants to manage Gmail and Google Calendar through natural language interactions.

Why google-workspace-alias-mcp?

• Unique: Only MCP with send-as alias support
• Unified: Gmail + Calendar in one package
• Full Featured: 28 tools with complete API coverage

✨ Why This MCP?

Feature	This MCP	Gmail MCP (Original)
Send-As Alias Support	✅ Dynamic discovery	❌ Not supported
Email Templates	✅ With variables	❌ Not supported
Scheduled Send	✅ Built-in	❌ Not supported
Gmail + Calendar	✅ Unified	❌ Gmail only
Multi-Account	✅ Planned	❌ Not supported
Free/Busy Check	✅ Built-in	❌ Not supported

🚀 Features

Gmail

• ✅ Send emails - with subject, content, attachments, and recipients
• ✅ Send-As Alias Support - dynamic discovery of all configured aliases
• ✅ Email templates - save and reuse templates with variables
• ✅ Scheduled send - schedule emails for later delivery
• ✅ Draft emails - create drafts without sending
• ✅ Read emails - get full email content with enhanced attachment display
• ✅ List emails - view inbox, sent, or custom labels
• ✅ Search emails - using Gmail search syntax
• ✅ Modify emails - mark read/unread, move to labels/folders
• ✅ Delete emails - permanent deletion
• ✅ Download attachments - save attachments to local filesystem
• ✅ Label management - create, update, delete labels
• ✅ Batch operations - process multiple emails efficiently
• ✅ Full attachment support - send and receive file attachments
• ✅ HTML emails - multipart messages with both HTML and plain text
• ✅ International characters - full support in subject and content

Google Calendar

• ✅ Create events - with title, time, description, location, attendees
• ✅ Get event - retrieve event details by ID
• ✅ List events - view events within specified time range
• ✅ Update events - modify existing events
• ✅ Delete events - remove events
• ✅ Search events - find events by query
• ✅ Free/Busy check - check availability across calendars
• ✅ Multi-calendar support - work with multiple calendars
• ✅ Recurring events - support for repeating events

📦 Installation

Using npm (Recommended)

npm install -g google-workspace-alias-mcp

Manual Installation

git clone https://github.com/johndelapena168/google-workspace-alias-mcp.git
cd google-workspace-mcp
npm install

⚙️ Setup

1. Create Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable the following APIs:
   • Gmail API
   • Google Calendar API

2. Create OAuth 2.0 Credentials

1. Go to "APIs & Services" > "Credentials"
2. Click "Create Credentials" > "OAuth client ID"
3. Select "Desktop app" as application type
4. Give it a name (e.g., "Google Workspace MCP")
5. Click "Create"
6. Download the JSON file
7. Rename it to gcp-oauth.keys.json

3. Authenticate

Place your gcp-oauth.keys.json in one of these locations:

• ~/.google-workspace-mcp/ (recommended)
• Current directory

Then run:

npx google-workspace-alias-mcp auth

This will:

1. Open your browser for Google authentication
2. Ask for permission to access Gmail and Calendar
3. Save credentials locally for future use

🔧 Configuration

Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["google-workspace-alias-mcp"]
    }
  }
}

Cursor

Add to your Cursor settings:

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["google-workspace-alias-mcp"]
    }
  }
}

Qoder

The MCP will be automatically detected when installed globally.

📖 Usage Examples

Send Email with Alias

{
  "tool": "send_email",
  "arguments": {
    "to": ["client@example.com"],
    "subject": "Project Update",
    "body": "Hi,\n\nHere's the latest update on the project.\n\nBest regards",
    "from": "hello@nexteraofai.com"
  }
}

List Available Aliases

{
  "tool": "list_aliases",
  "arguments": {}
}

List Email Templates

{
  "tool": "list_templates",
  "arguments": {}
}

Send Email Using Template

{
  "tool": "send_template_email",
  "arguments": {
    "template": "meeting-followup",
    "to": ["client@example.com"],
    "variables": {
      "name": "John",
      "meeting_name": "Project Review",
      "summary": "Discussed project timeline and milestones",
      "next_steps": "1. Finalize requirements\n2. Start development",
      "sender_name": "John Dela Pena"
    },
    "from": "hello@nexteraofai.com"
  }
}

Create Custom Template

{
  "tool": "create_template",
  "arguments": {
    "name": "weekly-report",
    "displayName": "Weekly Report",
    "subject": "Weekly Report: {{week_date}}",
    "body": "Hi {{name}},\n\nHere's the weekly report for {{week_date}}:\n\n{{report_content}}\n\nBest regards,\n{{sender_name}}"
  }
}

Schedule Email for Later

{
  "tool": "send_scheduled_email",
  "arguments": {
    "to": ["team@example.com"],
    "subject": "Weekly Update",
    "body": "Here's the weekly project update...",
    "scheduledTime": "2026-07-15T09:00:00",
    "from": "hello@nexteraofai.com"
  }
}

Create Calendar Event

{
  "tool": "create_event",
  "arguments": {
    "summary": "Project Kickoff Meeting",
    "description": "Initial meeting to discuss project scope and timeline",
    "location": "Zoom Meeting",
    "start": "2026-07-15T14:00:00",
    "end": "2026-07-15T15:00:00",
    "attendees": ["john@example.com", "jane@example.com"],
    "reminders": [
      { "method": "email", "minutes": 60 },
      { "method": "popup", "minutes": 10 }
    ]
  }
}

Search Events

{
  "tool": "search_events",
  "arguments": {
    "query": "meeting",
    "timeMin": "2026-07-01T00:00:00Z",
    "timeMax": "2026-07-31T23:59:59Z",
    "maxResults": 20
  }
}

Check Free/Busy

{
  "tool": "get_freebusy",
  "arguments": {
    "timeMin": "2026-07-15T09:00:00Z",
    "timeMax": "2026-07-15T17:00:00Z",
    "calendars": ["primary", "work@example.com"]
  }
}

Get Event by ID

{
  "tool": "get_event",
  "arguments": {
    "calendarId": "primary",
    "eventId": "abc123def456"
  }
}

List Emails in Inbox

{
  "tool": "list_emails",
  "arguments": {
    "labelIds": ["INBOX"],
    "maxResults": 10
  }
}

Mark Email as Read

{
  "tool": "modify_email",
  "arguments": {
    "messageId": "18a1b2c3d4e5f6789",
    "removeLabelIds": ["UNREAD"]
  }
}

Move Email to Label

{
  "tool": "modify_email",
  "arguments": {
    "messageId": "18a1b2c3d4e5f6789",
    "addLabelIds": ["Label_123"],
    "removeLabelIds": ["INBOX"]
  }
}

Download Attachment

{
  "tool": "download_attachment",
  "arguments": {
    "messageId": "18a1b2c3d4e5f6789",
    "attachmentId": "ANGjdJ8z7_OQ",
    "savePath": "C:/Users/Downloads"
  }
}

Create New Label

{
  "tool": "create_label",
  "arguments": {
    "name": "Client Projects",
    "messageListVisibility": "show",
    "labelListVisibility": "labelShow"
  }
}

Batch Delete Emails

{
  "tool": "batch_delete_emails",
  "arguments": {
    "messageIds": ["msg1", "msg2", "msg3"]
  }
}

🎯 Unique Selling Points

1. Dynamic Alias Support

No other MCP server supports Gmail send-as aliases. This MCP automatically discovers all configured aliases and lets you send from any of them.

2. Email Templates

Save frequently used email templates with variables:

"Use meeting-followup template for {{name}}"

3. Scheduled Send

Schedule emails for later delivery:

{
  "scheduledTime": "2026-07-15T09:00:00"
}

4. Unified Workspace

Gmail + Calendar in one MCP server. No need to install separate servers.

🔐 Security

• OAuth credentials are stored locally in ~/.google-workspace-mcp/
• Tokens are automatically refreshed when expired
• No data is sent to third-party servers
• Full control over permissions

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

git clone https://github.com/johndelapena168/google-workspace-alias-mcp.git
cd google-workspace-mcp
npm install
npm start

📝 License

MIT License - see LICENSE file

🙏 Acknowledgments

• Inspired by Gmail-MCP-Server by GongRzhe
• Built with Model Context Protocol SDK
• Uses Google APIs

📧 Contact

• GitHub: @johndelapena168
• Email: hello@nexteraofai.com

⭐ Support

If you find this MCP useful, please give it a star on GitHub!