Google Workspace MCP Server

A Model Context Protocol (MCP) server that provides comprehensive Google Workspace integration for AI agents. This server enables AI agents to interact with Gmail, Google Calendar, and Google Meet through a secure, well-structured API.

Features

📧 Gmail Integration

• Search emails with Gmail query syntax
• Send emails with attachment support (requires confirmation)
• Create drafts for later editing
• Extract attachments from emails with optional content analysis

📅 Google Calendar Integration

• List events with flexible filtering
• Create events with attendees and recurrence
• Update existing events
• Delete events (requires confirmation)
• List available calendars
• Create meetings with Google Meet integration

🎥 Google Meet Integration

• List conference records with filtering
• Access transcripts and transcript entries
• Retrieve recordings and metadata
• Get meeting details and participant information

Installation

npm install
npm run build

Setup

1. Google Cloud Console Setup

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the required APIs:
   • Gmail API
   • Google Calendar API
   • Google Meet API
4. Create OAuth2 credentials:
   • Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client IDs"
   • Choose "Desktop application"
   • Download the credentials JSON

2. Environment Configuration

cp .env.example .env

Edit .env with your Google OAuth2 credentials:

GOOGLE_CLIENT_ID=your_google_client_id_here
GOOGLE_CLIENT_SECRET=your_google_client_secret_here

3. Authentication

This MCP server supports two authentication methods:

Option A: OAuth2 Authentication (User-based)

For user-specific access where each user authenticates individually:

1. Run the server
2. When prompted, visit the authentication URL in your browser
3. Grant the necessary permissions
4. Tokens will be stored locally for future use

You can also set these environment variables directly:

• GOOGLE_ACCESS_TOKEN - OAuth access token
• GOOGLE_REFRESH_TOKEN - OAuth refresh token
• GOOGLE_TOKEN_TYPE - Token type (usually "Bearer")
• GOOGLE_TOKEN_EXPIRY - Token expiration timestamp
• GOOGLE_TOKENS_JSON - Complete token object as JSON string

Option B: Service Account Authentication (Recommended for Organizations)

For server-to-server authentication without user interaction:

Using Service Account Key File:

export GOOGLE_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account-key.json
export [email protected]  # Optional: for domain-wide delegation

Using Service Account Key JSON Content:

export GOOGLE_SERVICE_ACCOUNT_KEY_JSON='{"type":"service_account","project_id":"...","private_key_id":"...",...}'
export [email protected]  # Optional: for domain-wide delegation

Using Individual Service Account Fields:

export GOOGLE_SERVICE_ACCOUNT_EMAIL=my-service-account@myproject.iam.gserviceaccount.com
export GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...
-----END PRIVATE KEY-----"
export [email protected]  # Optional: for domain-wide delegation

Setting up Service Account:

1. Go to Google Cloud Console
2. Select your project or create a new one
3. Go to "IAM & Admin" > "Service Accounts"
4. Click "Create Service Account"
5. Fill in the details and create
6. Click on the created service account
7. Go to "Keys" tab and create a new JSON key
8. Enable the required APIs (Gmail, Calendar, Meet, etc.)

Domain-wide Delegation (Optional):

For accessing users' data across your organization:

1. In Google Cloud Console, edit your service account
2. Check "Enable Google Workspace Domain-wide Delegation"
3. Note the "Client ID" shown
4. In Google Admin Console, go to Security > API Controls > Domain-wide Delegation
5. Add the Client ID with these scopes:
   • https://www.googleapis.com/auth/gmail.readonly
   • https://www.googleapis.com/auth/gmail.send
   • https://www.googleapis.com/auth/gmail.compose
   • https://www.googleapis.com/auth/calendar
   • https://www.googleapis.com/auth/meetings.space.readonly

Then set GOOGLE_SERVICE_ACCOUNT_SUBJECT to the email address you want to impersonate.

Usage

Running the Server

# Development mode
npm run dev

# Production mode
npm start

Available Tools

Gmail Tools

• gmail_search - Search emails using Gmail query syntax
• gmail_send - Send emails (requires confirm: true)
• gmail_create_draft - Create draft emails
• gmail_get_attachments - Extract attachments from emails

Calendar Tools

• calendar_list_events - List calendar events
• calendar_create_event - Create new events (requires confirm: true)
• calendar_update_event - Update existing events (requires confirm: true)
• calendar_delete_event - Delete events (requires confirm: true)
• calendar_list_calendars - List available calendars
• calendar_create_meeting - Create meeting with Google Meet (requires confirm: true)

Meet Tools

• meet_list_conference_records - List past conference records
• meet_get_transcript - Get specific transcript
• meet_list_transcripts - List transcripts for a conference
• meet_get_recording - Get specific recording
• meet_list_recordings - List recordings for a conference
• meet_list_transcript_entries - List individual transcript entries

Tool Examples

Search Gmail

{
  "name": "gmail_search",
  "arguments": {
    "query": "from:[email protected] is:unread"
  }
}

Send Email

{
  "name": "gmail_send",
  "arguments": {
    "to": "[email protected]",
    "subject": "Hello from AI Agent",
    "body": "This email was sent via the MCP server!",
    "confirm": true
  }
}

Create Calendar Event

{
  "name": "calendar_create_event",
  "arguments": {
    "summary": "Team Meeting",
    "description": "Weekly team sync",
    "start_time": "2024-01-15T10:00:00Z",
    "end_time": "2024-01-15T11:00:00Z",
    "attendees": ["[email protected]"],
    "confirm": true
  }
}

Create Meeting with Google Meet

{
  "name": "calendar_create_meeting",
  "arguments": {
    "summary": "Project Discussion",
    "start_time": "2024-01-15T14:00:00Z",
    "end_time": "2024-01-15T15:00:00Z",
    "attendees": ["[email protected]", "[email protected]"],
    "confirm": true
  }
}

Security Features

• Multiple Authentication Methods: Support for both OAuth2 and Service Account authentication
• OAuth2 Authentication: Secure token-based authentication with automatic refresh
• Service Account Authentication: Server-to-server authentication for organizational use
• Domain-wide Delegation: Optional support for impersonating users in your organization
• Confirmation Required: Destructive operations (send, create, update, delete) require explicit confirmation
• Scoped Permissions: Only requests necessary Google API scopes
• Token Storage: Encrypted local token storage with automatic cleanup

Multi-User Support

The server supports multiple Google accounts through the user_id parameter:

{
  "name": "gmail_search",
  "arguments": {
    "user_id": "work_account",
    "query": "is:unread"
  }
}

Error Handling

The server provides comprehensive error handling with:

• Clear error messages
• Authentication guidance
• Structured error responses
• Graceful fallbacks

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Type checking
npm run typecheck

# Linting
npm run lint

# Code formatting
npm run format

Architecture

src/
├── auth/           # OAuth2 authentication management
├── handlers/       # Service-specific handlers (Gmail, Calendar, Meet)
├── types/          # TypeScript type definitions
├── utils/          # Utility functions (email formatting, etc.)
└── server.ts       # Main MCP server implementation

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

1. Check the existing issues
2. Review the Google Workspace API documentation
3. Create a new issue with detailed information

Requirements

• Node.js 18+
• Google Cloud project with Workspace APIs enabled
• Valid OAuth2 credentials OR Service Account credentials