gmail-workspace-mcp-server

Gmail Workspace MCP Server

An MCP (Model Context Protocol) server that provides Gmail integration for AI assistants. Supports both personal Gmail accounts (via OAuth2) and Google Workspace accounts (via service account with domain-wide delegation).

Features

• List Email Conversations: Retrieve emails with label filtering
• Get Email Details: Fetch full email content including body and attachments info
• Search Emails: Search using Gmail's powerful query syntax
• Manage Emails: Mark as read/unread, star/unstar, archive, apply labels
• Create Drafts: Compose draft emails with reply support
• Send Emails: Send new emails or replies, directly or from drafts
• Two Auth Methods: OAuth2 for personal accounts, Service Account for Google Workspace

Installation

npm install gmail-workspace-mcp-server

Or run directly with npx:

npx gmail-workspace-mcp-server

Authentication

This server supports two authentication modes. Choose the one that matches your account type.

Option 1: OAuth2 (Personal Gmail Accounts)

Use this for personal @gmail.com accounts or any Google account without Workspace admin access.

Prerequisites

• Go to Google Cloud Console
• Create or select a project
• Enable the Gmail API
• Configure the OAuth consent screen:
  • Choose External user type
  • Add yourself as a test user
  • Publish the app (click "Publish" on the consent screen) to prevent refresh tokens from expiring every 7 days. No full Google verification is needed for personal use.
• Create OAuth 2.0 credentials:
  • Choose Desktop app as the application type
  • Important: Create new credentials after publishing the app
• Copy the Client ID and Client Secret

Getting a Refresh Token

Run the built-in setup command:

npx gmail-workspace-mcp-server oauth-setup <client_id> <client_secret>

You can also pass credentials via environment variables:

GMAIL_OAUTH_CLIENT_ID=... GMAIL_OAUTH_CLIENT_SECRET=... npx gmail-workspace-mcp-server oauth-setup

Port conflict? If port 3000 is already in use, specify a different port:

PORT=3001 npx gmail-workspace-mcp-server oauth-setup <client_id> <client_secret>

Desktop app credentials automatically allow http://localhost redirects on any port, so no additional Google Cloud Console configuration is needed.

This will open your browser for Google sign-in and print the refresh token. You only need to do this once — the refresh token does not expire (as long as the OAuth consent screen is published).

Environment Variables (OAuth2)

Variable	Required	Description
GMAIL_OAUTH_CLIENT_ID	Yes	OAuth2 client ID from Google Cloud Console
GMAIL_OAUTH_CLIENT_SECRET	Yes	OAuth2 client secret
GMAIL_OAUTH_REFRESH_TOKEN	Yes	Refresh token from the setup script
GMAIL_ENABLED_TOOLGROUPS	No	Comma-separated list of tool groups (default: all)

Claude Desktop Configuration (OAuth2)

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["gmail-workspace-mcp-server"],
      "env": {
        "GMAIL_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GMAIL_OAUTH_CLIENT_SECRET": "your-client-secret",
        "GMAIL_OAUTH_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Option 2: Service Account (Google Workspace)

Use this for Google Workspace organizations where a domain admin can grant domain-wide delegation.

Prerequisites

• Go to Google Cloud Console
• Create or select a project
• Enable the Gmail API
• Create a service account with domain-wide delegation enabled
• In Google Workspace Admin Console, grant the service account access to the following scopes:
  • https://www.googleapis.com/auth/gmail.readonly (read emails)
  • https://www.googleapis.com/auth/gmail.modify (modify labels)
  • https://www.googleapis.com/auth/gmail.compose (create drafts)
  • https://www.googleapis.com/auth/gmail.send (send emails)
• Download the JSON key file

Environment Variables (Service Account)

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
GMAIL_ENABLED_TOOLGROUPS	No	Comma-separated list of tool groups to enable (default: all groups)

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

Claude Desktop Configuration (Service Account)

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

Note: For the private key, you can either:

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

Tool Groups

The server supports three tool groups for permission-based access control:

Group	Tools Included	Risk Level
readonly	list_email_conversations, get_email_conversation, search_email_conversations, list_draft_emails	Low
readwrite	All readonly tools + change_email_conversation, upsert_draft_email	Medium
readwrite_external	All readwrite tools + send_email	High

By default, all tool groups are enabled. To restrict access, set the GMAIL_ENABLED_TOOLGROUPS environment variable:

# Read-only access (no write/send capabilities)
GMAIL_ENABLED_TOOLGROUPS=readonly

# Read and write, but no external sending
GMAIL_ENABLED_TOOLGROUPS=readwrite

# Full access including sending emails (default)
GMAIL_ENABLED_TOOLGROUPS=readwrite_external

Security Note: The send_email tool is in a separate readwrite_external group because it can send emails externally, which carries higher risk than internal operations like modifying labels or creating drafts.

Available Tools

list_email_conversations

List email conversations from Gmail with optional filtering.

Parameters:

• count (number, optional): Number of emails to return (default: 10, max: 100)
• labels (string, optional): Comma-separated label IDs to filter by (default: "INBOX")
• sort_by (string, optional): Sort order - "recent" (newest first) or "oldest" (default: recent)
• after (string, optional): Only return emails after this datetime, exclusive (ISO 8601 UTC, e.g., "2024-01-15T14:30:00Z")
• before (string, optional): Only return emails before this datetime, exclusive (ISO 8601 UTC, e.g., "2024-01-15T14:30:00Z")

Example:

{
  "count": 20,
  "labels": "INBOX,STARRED",
  "after": "2024-01-15T00:00:00Z",
  "before": "2024-01-20T23:59:59Z"
}

get_email_conversation

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"
}

search_email_conversations

Search emails using Gmail's powerful query syntax.

Parameters:

• query (string, required): Gmail search query (e.g., "from:[e-mail]", "is:unread", "subject:meeting")
• count (number, optional): Maximum results to return (default: 10, max: 100)

Example:

{
  "query": "from:[e-mail] is:unread",
  "count": 20
}

change_email_conversation

Modify email labels and status (read/unread, starred, archived).

Parameters:

• email_id (string, required): The email ID to modify
• status (string, optional): "read", "unread", or "archived"
• is_starred (boolean, optional): Star or unstar the email
• labels (string, optional): Comma-separated labels to add
• remove_labels (string, optional): Comma-separated labels to remove

Example:

{
  "email_id": "18abc123def456",
  "status": "read",
  "is_starred": true
}

list_draft_emails

List draft emails from Gmail with optional thread filtering.

Parameters:

• count (number, optional): Maximum number of drafts to return (default: 10, max: 100)
• thread_id (string, optional): Filter drafts by conversation thread ID

Example:

{
  "thread_id": "18abc123def456"
}

upsert_draft_email

Create, update, or delete a draft email. Optionally as a reply to an existing conversation.

Parameters:

• draft_id (string, optional): ID of an existing draft to update or delete (omit to create a new draft)
• delete (boolean, optional): Set to true to delete the draft specified by draft_id. All other parameters are ignored when deleting
• to (string, required for create/update): Recipient email address
• subject (string, required for create/update): Email subject
• plaintext_body (string): Plain text body content (at least one of plaintext_body or html_body required for create/update)
• html_body (string): HTML body content for rich text formatting (at least one of plaintext_body or html_body required for create/update)
• cc (string, optional): CC recipients
• bcc (string, optional): BCC recipients
• thread_id (string, optional): Thread ID for replies
• reply_to_email_id (string, optional): Email ID to reply to (sets References/In-Reply-To headers)

For create/update: at least one of plaintext_body or html_body must be provided. If both are provided, a multipart email is sent with both versions.

Example (create new draft):

{
  "to": "[e-mail]",
  "subject": "Meeting Follow-up",
  "plaintext_body": "Thanks for the meeting today!"
}

Example (update existing draft):

{
  "draft_id": "r123456789",
  "to": "[e-mail]",
  "subject": "Meeting Follow-up (revised)",
  "html_body": "<p>Thanks for the meeting today! Check out <a href=\"https://example.com/notes\">the notes</a>.</p>"
}

Example (delete a draft):

{
  "draft_id": "r123456789",
  "delete": true
}

send_email

Send an email directly or from an existing draft.

Parameters:

• to (string, conditional): Recipient email (required unless sending from draft)
• subject (string, conditional): Email subject (required unless sending from draft)
• plaintext_body (string): Plain text body content (at least one of plaintext_body or html_body required, unless sending a draft)
• html_body (string): HTML body content for rich text formatting (at least one of plaintext_body or html_body required, unless sending a draft)
• cc (string, optional): CC recipients
• bcc (string, optional): BCC recipients
• from_draft_id (string, optional): Send an existing draft by ID
• thread_id (string, optional): Thread ID for replies
• reply_to_email_id (string, optional): Email ID to reply to

Example (plain text email):

{
  "to": "[e-mail]",
  "subject": "Hello",
  "plaintext_body": "This is a test email."
}

Example (HTML email):

{
  "to": "[e-mail]",
  "subject": "Hello",
  "html_body": "<p>Check out <a href=\"https://example.com\">our website</a> for more details.</p>"
}

Example (send draft):

{
  "from_draft_id": "r123456789"
}

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 credentials)
npm run test:manual

License

MIT