Gmail Workspace MCP Server

An MCP (Model Context Protocol) server that provides Gmail integration for AI assistants using Google Workspace service accounts with domain-wide delegation.

Features

• List Recent Emails: Retrieve recent emails within a specified time horizon
• Get Email Details: Fetch full email content including body and attachments info
• Service Account Authentication: Secure domain-wide delegation for Google Workspace organizations

Installation

npm install gmail-workspace-mcp-server

Or run directly with npx:

npx gmail-workspace-mcp-server

Prerequisites

This server requires a Google Cloud service account with domain-wide delegation to access Gmail on behalf of users in your Google Workspace domain.

Setup Steps

1. Go to Google Cloud Console
2. Create or select a project
3. Enable the Gmail API
4. Create a service account with domain-wide delegation enabled
5. In Google Workspace Admin Console, grant the service account access to the https://www.googleapis.com/auth/gmail.readonly scope
6. Download the JSON key file

Environment Variables

| Variable | Required | Description | | ------------------------------------ | -------- | ---------------------------------------- | | GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL | Yes | Service account email address | | GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY | Yes | Service account private key (PEM format) | | GMAIL_IMPERSONATE_EMAIL | Yes | Email address to impersonate |

You can find the client_email and private_key values in your service account JSON key file.

Configuration

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["gmail-workspace-mcp-server"],
      "env": {
        "GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL": "[email protected]",
        "GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----",
        "GMAIL_IMPERSONATE_EMAIL": "[email protected]"
      }
    }
  }
}

Note: For the private key, you can either:

1. Use the key directly with \n for newlines (as shown above)
2. Set the environment variable from a shell that preserves newlines

Available Tools

gmail_list_recent_emails

List recent emails from Gmail within a specified time horizon.

Parameters:

• hours (number, optional): Time horizon in hours (default: 24)
• labels (string, optional): Comma-separated label IDs (default: "INBOX")
• max_results (number, optional): Maximum emails to return (default: 10, max: 100)

Example:

{
  "hours": 48,
  "labels": "INBOX,STARRED",
  "max_results": 20
}

gmail_get_email

Retrieve the full content of a specific email by its ID.

Parameters:

• email_id (string, required): The unique identifier of the email

Example:

{
  "email_id": "18abc123def456"
}

Development

Setup

# Install dependencies
npm run install-all

# Build
npm run build

# Run in development mode
npm run dev

Testing

# Run functional tests
npm test

# Run integration tests
npm run test:integration

# Run manual tests (requires service account credentials)
npm run test:manual

License

MIT