# 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)

```bash
npm install -g google-workspace-alias-mcp
```

### Manual Installation

```bash
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](https://console.cloud.google.com/)
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:

```bash
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`):

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

### Cursor

Add to your Cursor settings:

```json
{
  "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

```json
{
  "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

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

### List Email Templates

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

### Send Email Using Template

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

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

### Check Free/Busy

```json
{
  "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

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

### List Emails in Inbox

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

### Mark Email as Read

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

### Move Email to Label

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

### Download Attachment

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

### Create New Label

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

### Batch Delete Emails

```json
{
  "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:
```json
{
  "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

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

## 📝 License

MIT License - see [LICENSE](LICENSE) file

## 🙏 Acknowledgments

- Inspired by [Gmail-MCP-Server](https://github.com/GongRzhe/Gmail-MCP-Server) by GongRzhe
- Built with [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- Uses [Google APIs](https://github.com/googleapis/google-api-nodejs-client)

## 📧 Contact

- GitHub: [@johndelapena168](https://github.com/johndelapena168)
- Email: hello@nexteraofai.com

## ⭐ Support

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