gmail-workspace-mcp-server 0.0.5 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+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
 
@@ -10,7 +10,7 @@ An MCP (Model Context Protocol) server that provides Gmail integration for AI as
 - **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
-- **Service Account Authentication**: Secure domain-wide delegation for Google Workspace organizations
+- **Two Auth Methods**: OAuth2 for personal accounts, Service Account for Google Workspace
 
 ## Installation
 
@@ -24,11 +24,86 @@ Or run directly with npx:
 npx gmail-workspace-mcp-server
 ```
 
-## Prerequisites
+## Authentication
 
-This server requires a Google Cloud service account with domain-wide delegation to access Gmail on behalf of users in your Google Workspace domain.
+This server supports two authentication modes. Choose the one that matches your account type.
 
-### Setup Steps
+### Option 1: OAuth2 (Personal Gmail Accounts)
+
+Use this for personal `@gmail.com` accounts or any Google account without Workspace admin access.
+
+#### Prerequisites
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create or select a project
+3. Enable the Gmail API
+4. 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.
+5. Create OAuth 2.0 credentials:
+   - Choose **Desktop app** as the application type
+   - **Important**: Create new credentials _after_ publishing the app
+6. Copy the Client ID and Client Secret
+
+#### Getting a Refresh Token
+
+Run the one-time setup script from a clone of the repository:
+
+```bash
+git clone https://github.com/pulsemcp/mcp-servers.git
+cd mcp-servers/experimental/gmail
+npx tsx scripts/oauth-setup.ts <client_id> <client_secret>
+```
+
+You can also pass credentials via environment variables:
+
+```bash
+GMAIL_OAUTH_CLIENT_ID=... GMAIL_OAUTH_CLIENT_SECRET=... npx tsx scripts/oauth-setup.ts
+```
+
+**Port conflict?** If port 3000 is already in use, specify a different port:
+
+```bash
+PORT=3001 npx tsx scripts/oauth-setup.ts <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)
+
+```json
+{
+  "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
 
 1. Go to [Google Cloud Console](https://console.cloud.google.com/)
 2. Create or select a project
@@ -41,7 +116,7 @@ This server requires a Google Cloud service account with domain-wide delegation
    - `https://www.googleapis.com/auth/gmail.send` (send emails)
 6. Download the JSON key file
 
-### Environment Variables
+#### Environment Variables (Service Account)
 
 | Variable                             | Required | Description                                                         |
 | ------------------------------------ | -------- | ------------------------------------------------------------------- |
@@ -52,7 +127,30 @@ This server requires a Google Cloud service account with domain-wide delegation
 
 You can find the `client_email` and `private_key` values in your service account JSON key file.
 
-### Tool Groups
+#### Claude Desktop Configuration (Service Account)
+
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "npx",
+      "args": ["gmail-workspace-mcp-server"],
+      "env": {
+        "GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL": "my-service-account@my-project.iam.gserviceaccount.com",
+        "GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----",
+        "GMAIL_IMPERSONATE_EMAIL": "user@yourdomain.com"
+      }
+    }
+  }
+}
+```
+
+**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
+
+## Tool Groups
 
 The server supports three tool groups for permission-based access control:
 
@@ -77,33 +175,6 @@ 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.
 
-## Configuration
-
-### Claude Desktop
-
-Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "gmail": {
-      "command": "npx",
-      "args": ["gmail-workspace-mcp-server"],
-      "env": {
-        "GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL": "my-service-account@my-project.iam.gserviceaccount.com",
-        "GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----",
-        "GMAIL_IMPERSONATE_EMAIL": "user@yourdomain.com"
-      }
-    }
-  }
-}
-```
-
-**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
 
 ### list_email_conversations
@@ -262,7 +333,7 @@ npm test
 # Run integration tests
 npm run test:integration
 
-# Run manual tests (requires service account credentials)
+# Run manual tests (requires credentials)
 npm run test:manual
 ```
 

package/build/index.integration-with-mock.js

@@ -61,6 +61,44 @@ const MOCK_EMAILS = [
         },
         sizeEstimate: 2048,
     },
+    {
+        id: 'msg_003',
+        threadId: 'thread_003',
+        labelIds: ['INBOX'],
+        snippet: 'Please find the invoice attached...',
+        historyId: '12347',
+        internalDate: String(Date.now() - 1000 * 60 * 60), // 1 hour ago
+        payload: {
+            mimeType: 'multipart/mixed',
+            headers: [
+                { name: 'Subject', value: 'Invoice Attached' },
+                { name: 'From', value: 'billing@example.com' },
+                { name: 'To', value: 'me@example.com' },
+                { name: 'Date', value: new Date(Date.now() - 1000 * 60 * 60).toISOString() },
+                { name: 'Message-ID', value: '<msg003@example.com>' },
+            ],
+            parts: [
+                {
+                    partId: '0',
+                    mimeType: 'text/plain',
+                    body: {
+                        size: 40,
+                        data: Buffer.from('Please find the invoice attached.').toString('base64url'),
+                    },
+                },
+                {
+                    partId: '1',
+                    mimeType: 'application/pdf',
+                    filename: 'invoice.pdf',
+                    body: {
+                        attachmentId: 'att_001',
+                        size: 1024,
+                    },
+                },
+            ],
+        },
+        sizeEstimate: 2048,
+    },
 ];
 const mockDrafts = [];
 let draftIdCounter = 1;
@@ -206,6 +244,16 @@ function createMockClient() {
             };
             return sentMessage;
         },
+        async getAttachment(_messageId, attachmentId) {
+            const mockData = {
+                att_001: Buffer.from('Mock PDF content').toString('base64url'),
+            };
+            const data = mockData[attachmentId];
+            if (!data) {
+                throw new Error(`Attachment not found: ${attachmentId}`);
+            }
+            return { data, size: Buffer.from(data, 'base64url').length };
+        },
         async sendDraft(draftId) {
             const draft = mockDrafts.find((d) => d.id === draftId);
             if (!draft) {

package/build/index.js

@@ -14,40 +14,95 @@ const VERSION = packageJson.version;
 // ENVIRONMENT VALIDATION
 // =============================================================================
 function validateEnvironment() {
-    const missing = [];
-    if (!process.env.GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL) {
-        missing.push('GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL');
+    // Check for OAuth2 credentials
+    const hasOAuth2 = process.env.GMAIL_OAUTH_CLIENT_ID &&
+        process.env.GMAIL_OAUTH_CLIENT_SECRET &&
+        process.env.GMAIL_OAUTH_REFRESH_TOKEN;
+    // Check for service account credentials
+    const hasServiceAccount = process.env.GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL &&
+        process.env.GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY &&
+        process.env.GMAIL_IMPERSONATE_EMAIL;
+    if (hasOAuth2 || hasServiceAccount) {
+        return;
     }
-    if (!process.env.GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY) {
-        missing.push('GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY');
-    }
-    if (!process.env.GMAIL_IMPERSONATE_EMAIL) {
-        missing.push('GMAIL_IMPERSONATE_EMAIL');
+    // Check for partial OAuth2 configuration
+    const oauthVars = {
+        GMAIL_OAUTH_CLIENT_ID: process.env.GMAIL_OAUTH_CLIENT_ID,
+        GMAIL_OAUTH_CLIENT_SECRET: process.env.GMAIL_OAUTH_CLIENT_SECRET,
+        GMAIL_OAUTH_REFRESH_TOKEN: process.env.GMAIL_OAUTH_REFRESH_TOKEN,
+    };
+    const hasPartialOAuth2 = Object.values(oauthVars).some(Boolean);
+    if (hasPartialOAuth2) {
+        const missingOAuth = Object.entries(oauthVars)
+            .filter(([, v]) => !v)
+            .map(([k]) => k);
+        logError('validateEnvironment', 'Incomplete OAuth2 configuration. Missing:');
+        for (const varName of missingOAuth) {
+            console.error(`  - ${varName}`);
+        }
+        console.error('\nOAuth2 mode requires all three variables:');
+        console.error('  GMAIL_OAUTH_CLIENT_ID: OAuth2 client ID from Google Cloud Console');
+        console.error('  GMAIL_OAUTH_CLIENT_SECRET: OAuth2 client secret');
+        console.error('  GMAIL_OAUTH_REFRESH_TOKEN: Refresh token from one-time consent flow');
+        console.error('\nRun the setup script to obtain a refresh token:');
+        console.error('  npx tsx scripts/oauth-setup.ts <client_id> <client_secret>');
+        console.error('\n======================================================\n');
+        process.exit(1);
     }
-    if (missing.length > 0) {
-        logError('validateEnvironment', 'Missing required environment variables:');
-        console.error('\nThis MCP server requires a Google Cloud service account with');
-        console.error('domain-wide delegation to access Gmail on behalf of users.');
-        console.error('\nRequired environment variables:');
+    // Check for partial service account configuration
+    const serviceAccountVars = {
+        GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL: process.env.GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL,
+        GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY: process.env.GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY,
+        GMAIL_IMPERSONATE_EMAIL: process.env.GMAIL_IMPERSONATE_EMAIL,
+    };
+    const hasPartialServiceAccount = Object.values(serviceAccountVars).some(Boolean);
+    if (hasPartialServiceAccount) {
+        const missingServiceAccount = Object.entries(serviceAccountVars)
+            .filter(([, v]) => !v)
+            .map(([k]) => k);
+        logError('validateEnvironment', 'Incomplete service account configuration. Missing:');
+        for (const varName of missingServiceAccount) {
+            console.error(`  - ${varName}`);
+        }
+        console.error('\nService account mode requires all three variables:');
         console.error('  GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL: Service account email address');
-        console.error('    Example: my-service-account@my-project.iam.gserviceaccount.com');
         console.error('  GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY: Service account private key (PEM format)');
-        console.error('    Example: -----BEGIN PRIVATE KEY-----\\nMIIE...\\n-----END PRIVATE KEY-----');
         console.error('  GMAIL_IMPERSONATE_EMAIL: Email address to impersonate');
-        console.error('    Example: user@yourdomain.com');
         console.error('\nSetup steps:');
         console.error('  1. Go to https://console.cloud.google.com/');
         console.error('  2. Create a service account with domain-wide delegation');
         console.error('  3. In Google Workspace Admin, grant required Gmail API scopes');
         console.error('  4. Download the JSON key file and extract client_email and private_key');
-        console.error('\nOptional environment variables:');
-        console.error('  GMAIL_ENABLED_TOOLGROUPS: Comma-separated list of tool groups to enable');
-        console.error('    Valid groups: readonly, readwrite, readwrite_external');
-        console.error('    Default: all groups enabled');
-        console.error('    Example: GMAIL_ENABLED_TOOLGROUPS=readwrite');
         console.error('\n======================================================\n');
         process.exit(1);
     }
+    // No credentials found at all
+    logError('validateEnvironment', 'Missing required environment variables:');
+    console.error('\nThis MCP server supports two authentication modes:\n');
+    console.error('--- Option 1: OAuth2 (for personal Gmail accounts) ---');
+    console.error('  GMAIL_OAUTH_CLIENT_ID: OAuth2 client ID from Google Cloud Console');
+    console.error('  GMAIL_OAUTH_CLIENT_SECRET: OAuth2 client secret');
+    console.error('  GMAIL_OAUTH_REFRESH_TOKEN: Refresh token from one-time consent flow');
+    console.error('\n  Setup: Run `npx tsx scripts/oauth-setup.ts <client_id> <client_secret>`');
+    console.error('\n--- Option 2: Service Account (for Google Workspace) ---');
+    console.error('  GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL: Service account email address');
+    console.error('    Example: my-service-account@my-project.iam.gserviceaccount.com');
+    console.error('  GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY: Service account private key (PEM format)');
+    console.error('    Example: -----BEGIN PRIVATE KEY-----\\nMIIE...\\n-----END PRIVATE KEY-----');
+    console.error('  GMAIL_IMPERSONATE_EMAIL: Email address to impersonate');
+    console.error('    Example: user@yourdomain.com');
+    console.error('\n  Setup steps:');
+    console.error('  1. Go to https://console.cloud.google.com/');
+    console.error('  2. Create a service account with domain-wide delegation');
+    console.error('  3. In Google Workspace Admin, grant required Gmail API scopes');
+    console.error('  4. Download the JSON key file and extract client_email and private_key');
+    console.error('\nOptional environment variables:');
+    console.error('  GMAIL_ENABLED_TOOLGROUPS: Comma-separated list of tool groups to enable');
+    console.error('    Valid groups: readonly, readwrite, readwrite_external');
+    console.error('    Default: all groups enabled');
+    console.error('    Example: GMAIL_ENABLED_TOOLGROUPS=readwrite');
+    console.error('\n======================================================\n');
+    process.exit(1);
 }
 // =============================================================================
 // MAIN ENTRY POINT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gmail-workspace-mcp-server",
-  "version": "0.0.5",
-  "description": "MCP server for Gmail integration with service account support",
+  "version": "0.1.1",
+  "description": "MCP server for Gmail integration with OAuth2 and service account support",
   "main": "build/index.js",
   "type": "module",
   "bin": {

package/shared/gmail-client/lib/get-attachment.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Attachment data returned by the Gmail API
+ */
+export interface AttachmentData {
+    /** Base64url-encoded attachment data */
+    data: string;
+    /** Size of the attachment in bytes */
+    size: number;
+}
+/**
+ * Gets attachment data for a specific attachment on a message
+ * Uses the Gmail API: GET /messages/{messageId}/attachments/{attachmentId}
+ */
+export declare function getAttachment(baseUrl: string, headers: Record<string, string>, messageId: string, attachmentId: string): Promise<AttachmentData>;

package/shared/gmail-client/lib/get-attachment.js

@@ -0,0 +1,16 @@
+import { handleApiError } from './api-errors.js';
+/**
+ * Gets attachment data for a specific attachment on a message
+ * Uses the Gmail API: GET /messages/{messageId}/attachments/{attachmentId}
+ */
+export async function getAttachment(baseUrl, headers, messageId, attachmentId) {
+    const url = `${baseUrl}/messages/${messageId}/attachments/${attachmentId}`;
+    const response = await fetch(url, {
+        method: 'GET',
+        headers,
+    });
+    if (!response.ok) {
+        handleApiError(response.status, 'getting attachment', attachmentId);
+    }
+    return (await response.json());
+}

package/shared/index.d.ts

@@ -1,4 +1,4 @@
-export { createMCPServer, createDefaultClient, ServiceAccountGmailClient, type IGmailClient, type ClientFactory, type ServiceAccountCredentials, type CreateMCPServerOptions, type Draft, } from './server.js';
+export { createMCPServer, createDefaultClient, ServiceAccountGmailClient, OAuth2GmailClient, GMAIL_SCOPES, type IGmailClient, type ClientFactory, type ServiceAccountCredentials, type CreateMCPServerOptions, type Draft, } from './server.js';
 export { createRegisterTools, registerTools, parseEnabledToolGroups, getAvailableToolGroups, type ToolGroup, } from './tools.js';
 export { logServerStart, logError, logWarning, logDebug } from './logging.js';
 export type { Email, EmailListItem, EmailHeader, EmailPart, Label, Thread, PaginatedResponse, } from './types.js';

package/shared/index.js

@@ -1,6 +1,6 @@
 // Main exports for Gmail MCP Server
 // Server and client
-export { createMCPServer, createDefaultClient, ServiceAccountGmailClient, } from './server.js';
+export { createMCPServer, createDefaultClient, ServiceAccountGmailClient, OAuth2GmailClient, GMAIL_SCOPES, } from './server.js';
 // Tools and tool groups
 export { createRegisterTools, registerTools, parseEnabledToolGroups, getAvailableToolGroups, } from './tools.js';
 // Logging utilities

package/shared/server.d.ts

@@ -1,5 +1,10 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { Email, EmailListItem } from './types.js';
+/**
+ * Gmail API scopes required by this server.
+ * Shared between service account JWT, OAuth2 consent flow, and documentation.
+ */
+export declare const GMAIL_SCOPES: readonly ["https://www.googleapis.com/auth/gmail.readonly", "https://www.googleapis.com/auth/gmail.modify", "https://www.googleapis.com/auth/gmail.compose", "https://www.googleapis.com/auth/gmail.send"];
 /**
  * Draft message structure
  */
@@ -91,6 +96,13 @@ export interface IGmailClient {
      * Send a draft
      */
     sendDraft(draftId: string): Promise<Email>;
+    /**
+     * Get attachment data by message ID and attachment ID
+     */
+    getAttachment(messageId: string, attachmentId: string): Promise<{
+        data: string;
+        size: number;
+    }>;
 }
 /**
  * Service account credentials structure
@@ -108,18 +120,32 @@ export interface ServiceAccountCredentials {
     client_x509_cert_url: string;
 }
 /**
- * Gmail API client implementation using service account with domain-wide delegation
+ * Abstract base class for Gmail API clients.
+ * Provides shared token management (caching, mutex refresh) and all
+ * IGmailClient method implementations. Subclasses only need to implement
+ * the authentication-specific methods.
  */
-export declare class ServiceAccountGmailClient implements IGmailClient {
-    private impersonateEmail;
-    private baseUrl;
-    private jwtClient;
+declare abstract class BaseGmailClient implements IGmailClient {
+    protected baseUrl: string;
     private cachedToken;
     private tokenExpiry;
     private refreshPromise;
-    constructor(credentials: ServiceAccountCredentials, impersonateEmail: string);
+    /**
+     * Perform the authentication-specific token refresh.
+     * Must set this.cachedToken and this.tokenExpiry via updateToken().
+     */
+    protected abstract refreshTokenImpl(): Promise<{
+        token: string;
+        expiryDate: number;
+    }>;
+    /**
+     * Get the sender email address for composing/sending emails.
+     * Service account uses the impersonation email; OAuth2 fetches from profile API.
+     */
+    protected abstract getSenderEmail(): Promise<string>;
+    protected updateToken(token: string, expiryDate: number): void;
     private refreshToken;
-    private getHeaders;
+    protected getHeaders(): Promise<Record<string, string>>;
     listMessages(options?: {
         q?: string;
         maxResults?: number;
@@ -172,6 +198,42 @@ export declare class ServiceAccountGmailClient implements IGmailClient {
         references?: string;
     }): Promise<Email>;
     sendDraft(draftId: string): Promise<Email>;
+    getAttachment(messageId: string, attachmentId: string): Promise<{
+        data: string;
+        size: number;
+    }>;
+}
+/**
+ * Gmail API client implementation using service account with domain-wide delegation
+ */
+export declare class ServiceAccountGmailClient extends BaseGmailClient {
+    private jwtClient;
+    private impersonateEmail;
+    constructor(credentials: ServiceAccountCredentials, impersonateEmail: string);
+    protected refreshTokenImpl(): Promise<{
+        token: string;
+        expiryDate: number;
+    }>;
+    protected getSenderEmail(): Promise<string>;
+}
+/**
+ * Gmail API client implementation using OAuth2 user authentication.
+ * Enables access to personal Gmail accounts (e.g., @gmail.com) that cannot
+ * use domain-wide delegation.
+ */
+export declare class OAuth2GmailClient extends BaseGmailClient {
+    private oauth2Client;
+    private userEmail;
+    constructor(clientId: string, clientSecret: string, refreshToken: string);
+    protected refreshTokenImpl(): Promise<{
+        token: string;
+        expiryDate: number;
+    }>;
+    /**
+     * Fetches the authenticated user's email address from the Gmail profile API.
+     * Caches the result for subsequent calls.
+     */
+    protected getSenderEmail(): Promise<string>;
 }
 export type ClientFactory = () => IGmailClient;
 export interface CreateMCPServerOptions {
@@ -179,10 +241,20 @@ export interface CreateMCPServerOptions {
 }
 /**
  * Creates the default Gmail client based on environment variables.
- * Uses service account with domain-wide delegation:
+ *
+ * Supports two authentication modes:
+ *
+ * 1. OAuth2 (for personal Gmail accounts):
+ *   - GMAIL_OAUTH_CLIENT_ID: OAuth2 client ID from Google Cloud Console
+ *   - GMAIL_OAUTH_CLIENT_SECRET: OAuth2 client secret
+ *   - GMAIL_OAUTH_REFRESH_TOKEN: Refresh token from one-time consent flow
+ *
+ * 2. Service Account (for Google Workspace accounts):
  *   - GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL: Service account email address
  *   - GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY: Service account private key (PEM format)
  *   - GMAIL_IMPERSONATE_EMAIL: Email address to impersonate
+ *
+ * If OAuth2 credentials are present, OAuth2 mode is used. Otherwise, service account mode is used.
  */
 export declare function createDefaultClient(): IGmailClient;
 export declare function createMCPServer(options: CreateMCPServerOptions): {
@@ -222,3 +294,4 @@ export declare function createMCPServer(options: CreateMCPServerOptions): {
     }>;
     registerHandlers: (server: Server, clientFactory?: ClientFactory) => Promise<void>;
 };
+export {};

package/shared/server.js

@@ -1,38 +1,34 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { JWT } from 'google-auth-library';
+import { JWT, OAuth2Client } from 'google-auth-library';
 import { createRegisterTools } from './tools.js';
 /**
- * Gmail API client implementation using service account with domain-wide delegation
+ * Gmail API scopes required by this server.
+ * Shared between service account JWT, OAuth2 consent flow, and documentation.
  */
-export class ServiceAccountGmailClient {
-    impersonateEmail;
+export const GMAIL_SCOPES = [
+    'https://www.googleapis.com/auth/gmail.readonly',
+    'https://www.googleapis.com/auth/gmail.modify',
+    'https://www.googleapis.com/auth/gmail.compose',
+    'https://www.googleapis.com/auth/gmail.send',
+];
+/**
+ * Abstract base class for Gmail API clients.
+ * Provides shared token management (caching, mutex refresh) and all
+ * IGmailClient method implementations. Subclasses only need to implement
+ * the authentication-specific methods.
+ */
+class BaseGmailClient {
     baseUrl = 'https://gmail.googleapis.com/gmail/v1/users/me';
-    jwtClient;
     cachedToken = null;
     tokenExpiry = 0;
     refreshPromise = null;
-    constructor(credentials, impersonateEmail) {
-        this.impersonateEmail = impersonateEmail;
-        this.jwtClient = new JWT({
-            email: credentials.client_email,
-            key: credentials.private_key,
-            scopes: [
-                'https://www.googleapis.com/auth/gmail.readonly',
-                'https://www.googleapis.com/auth/gmail.modify',
-                'https://www.googleapis.com/auth/gmail.compose',
-                'https://www.googleapis.com/auth/gmail.send',
-            ],
-            subject: impersonateEmail,
-        });
+    updateToken(token, expiryDate) {
+        this.cachedToken = token;
+        this.tokenExpiry = expiryDate;
     }
     async refreshToken() {
-        const tokenResponse = await this.jwtClient.authorize();
-        if (!tokenResponse.access_token) {
-            throw new Error('Failed to obtain access token from service account');
-        }
-        this.cachedToken = tokenResponse.access_token;
-        // Token typically expires in 1 hour, but use the actual expiry if provided
-        this.tokenExpiry = tokenResponse.expiry_date || Date.now() + 3600000;
+        const { token, expiryDate } = await this.refreshTokenImpl();
+        this.updateToken(token, expiryDate);
     }
     async getHeaders() {
         // Check if we have a valid cached token (with 60 second buffer)
@@ -71,8 +67,9 @@ export class ServiceAccountGmailClient {
     }
     async createDraft(options) {
         const headers = await this.getHeaders();
+        const senderEmail = await this.getSenderEmail();
         const { createDraft } = await import('./gmail-client/lib/drafts.js');
-        return createDraft(this.baseUrl, headers, this.impersonateEmail, options);
+        return createDraft(this.baseUrl, headers, senderEmail, options);
     }
     async getDraft(draftId) {
         const headers = await this.getHeaders();
@@ -91,23 +88,134 @@ export class ServiceAccountGmailClient {
     }
     async sendMessage(options) {
         const headers = await this.getHeaders();
+        const senderEmail = await this.getSenderEmail();
         const { sendMessage } = await import('./gmail-client/lib/send-message.js');
-        return sendMessage(this.baseUrl, headers, this.impersonateEmail, options);
+        return sendMessage(this.baseUrl, headers, senderEmail, options);
     }
     async sendDraft(draftId) {
         const headers = await this.getHeaders();
         const { sendDraft } = await import('./gmail-client/lib/send-message.js');
         return sendDraft(this.baseUrl, headers, draftId);
     }
+    async getAttachment(messageId, attachmentId) {
+        const headers = await this.getHeaders();
+        const { getAttachment } = await import('./gmail-client/lib/get-attachment.js');
+        return getAttachment(this.baseUrl, headers, messageId, attachmentId);
+    }
+}
+/**
+ * Gmail API client implementation using service account with domain-wide delegation
+ */
+export class ServiceAccountGmailClient extends BaseGmailClient {
+    jwtClient;
+    impersonateEmail;
+    constructor(credentials, impersonateEmail) {
+        super();
+        this.impersonateEmail = impersonateEmail;
+        this.jwtClient = new JWT({
+            email: credentials.client_email,
+            key: credentials.private_key,
+            scopes: [...GMAIL_SCOPES],
+            subject: impersonateEmail,
+        });
+    }
+    async refreshTokenImpl() {
+        const tokenResponse = await this.jwtClient.authorize();
+        if (!tokenResponse.access_token) {
+            throw new Error('Failed to obtain access token from service account');
+        }
+        return {
+            token: tokenResponse.access_token,
+            // Token typically expires in 1 hour, but use the actual expiry if provided
+            expiryDate: tokenResponse.expiry_date || Date.now() + 3600000,
+        };
+    }
+    async getSenderEmail() {
+        return this.impersonateEmail;
+    }
+}
+/**
+ * Gmail API client implementation using OAuth2 user authentication.
+ * Enables access to personal Gmail accounts (e.g., @gmail.com) that cannot
+ * use domain-wide delegation.
+ */
+export class OAuth2GmailClient extends BaseGmailClient {
+    oauth2Client;
+    userEmail = null;
+    constructor(clientId, clientSecret, refreshToken) {
+        super();
+        this.oauth2Client = new OAuth2Client(clientId, clientSecret);
+        this.oauth2Client.setCredentials({ refresh_token: refreshToken });
+    }
+    async refreshTokenImpl() {
+        const { token, res } = await this.oauth2Client.getAccessToken();
+        if (!token) {
+            throw new Error('Failed to obtain access token from OAuth2 refresh token');
+        }
+        // Use expiry from response if available, otherwise default to 1 hour
+        const expiryDate = res?.data?.expiry_date;
+        return {
+            token,
+            expiryDate: typeof expiryDate === 'number' ? expiryDate : Date.now() + 3600000,
+        };
+    }
+    /**
+     * Fetches the authenticated user's email address from the Gmail profile API.
+     * Caches the result for subsequent calls.
+     */
+    async getSenderEmail() {
+        if (this.userEmail) {
+            return this.userEmail;
+        }
+        const headers = await this.getHeaders();
+        const response = await fetch(`${this.baseUrl}/profile`, {
+            method: 'GET',
+            headers,
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => '');
+            throw new Error(`Failed to fetch Gmail profile: ${response.status} ${response.statusText}${body ? ` - ${body}` : ''}`);
+        }
+        const profile = (await response.json());
+        this.userEmail = profile.emailAddress;
+        return this.userEmail;
+    }
 }
 /**
  * Creates the default Gmail client based on environment variables.
- * Uses service account with domain-wide delegation:
+ *
+ * Supports two authentication modes:
+ *
+ * 1. OAuth2 (for personal Gmail accounts):
+ *   - GMAIL_OAUTH_CLIENT_ID: OAuth2 client ID from Google Cloud Console
+ *   - GMAIL_OAUTH_CLIENT_SECRET: OAuth2 client secret
+ *   - GMAIL_OAUTH_REFRESH_TOKEN: Refresh token from one-time consent flow
+ *
+ * 2. Service Account (for Google Workspace accounts):
  *   - GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL: Service account email address
  *   - GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY: Service account private key (PEM format)
  *   - GMAIL_IMPERSONATE_EMAIL: Email address to impersonate
+ *
+ * If OAuth2 credentials are present, OAuth2 mode is used. Otherwise, service account mode is used.
  */
 export function createDefaultClient() {
+    // Check for OAuth2 credentials first
+    const oauthClientId = process.env.GMAIL_OAUTH_CLIENT_ID;
+    const oauthClientSecret = process.env.GMAIL_OAUTH_CLIENT_SECRET;
+    const oauthRefreshToken = process.env.GMAIL_OAUTH_REFRESH_TOKEN;
+    if (oauthClientId && oauthClientSecret && oauthRefreshToken) {
+        return new OAuth2GmailClient(oauthClientId, oauthClientSecret, oauthRefreshToken);
+    }
+    // Warn if some OAuth2 vars are set but not all (likely misconfiguration)
+    if (oauthClientId || oauthClientSecret || oauthRefreshToken) {
+        const missing = [
+            !oauthClientId && 'GMAIL_OAUTH_CLIENT_ID',
+            !oauthClientSecret && 'GMAIL_OAUTH_CLIENT_SECRET',
+            !oauthRefreshToken && 'GMAIL_OAUTH_REFRESH_TOKEN',
+        ].filter(Boolean);
+        console.warn(`Warning: Partial OAuth2 configuration detected. Missing: ${missing.join(', ')}. Falling back to service account mode.`);
+    }
+    // Fall back to service account mode
     const clientEmail = process.env.GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL;
     // Handle both literal \n in JSON configs and actual newlines
     const privateKey = process.env.GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY?.replace(/\\n/g, '\n');

package/shared/tools/download-email-attachments.d.ts

@@ -0,0 +1,50 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const DownloadEmailAttachmentsSchema: z.ZodObject<{
+    email_id: z.ZodString;
+    filename: z.ZodOptional<z.ZodString>;
+    inline: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    email_id: string;
+    inline: boolean;
+    filename?: string | undefined;
+}, {
+    email_id: string;
+    filename?: string | undefined;
+    inline?: boolean | undefined;
+}>;
+export declare function downloadEmailAttachmentsTool(_server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            email_id: {
+                type: string;
+                description: string;
+            };
+            filename: {
+                type: string;
+                description: string;
+            };
+            inline: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};

package/shared/tools/download-email-attachments.js

@@ -0,0 +1,276 @@
+import { writeFile, mkdir } from 'fs/promises';
+import { join, basename, extname } from 'path';
+import { z } from 'zod';
+/** Maximum total size (in bytes) for inline attachments (25 MB) */
+const MAX_INLINE_SIZE = 25 * 1024 * 1024;
+const PARAM_DESCRIPTIONS = {
+    email_id: 'The unique identifier of the email containing the attachment(s). ' +
+        'Obtain this from list_email_conversations, search_email_conversations, or get_email_conversation.',
+    filename: 'Optional filename to download a specific attachment. ' +
+        'If omitted, all attachments on the email are downloaded.',
+    inline: 'When true, return attachment content directly in the response (text-based files as text, binary as base64). ' +
+        'When false (default), save attachments to /tmp/ and return file paths.',
+};
+export const DownloadEmailAttachmentsSchema = z.object({
+    email_id: z.string().min(1).describe(PARAM_DESCRIPTIONS.email_id),
+    filename: z.string().optional().describe(PARAM_DESCRIPTIONS.filename),
+    inline: z.boolean().optional().default(false).describe(PARAM_DESCRIPTIONS.inline),
+});
+const TOOL_DESCRIPTION = `Download attachment content from a specific email.
+
+By default, saves all attachments to /tmp/ and returns the file paths. Use the inline parameter to return content directly in the response instead.
+
+**Parameters:**
+- email_id: The unique identifier of the email (required)
+- filename: Download only the attachment matching this filename (optional)
+- inline: If true, return content in the response instead of saving to files (optional, default: false)
+
+**Default behavior (inline=false):**
+Saves attachments as files to /tmp/ and returns the full file paths. Best for binary files or large attachments where you need to process the file afterward.
+
+**Inline behavior (inline=true):**
+Returns content directly. Text-based attachments (text/*, JSON, XML) are decoded to text. Binary attachments (PDF, images, etc.) are returned as base64. Total size is capped at 25 MB.
+
+**Use cases:**
+- Download invoices, receipts, or documents attached to emails
+- Extract data from CSV or text file attachments
+- Access PDF attachments for processing
+- Batch-download all attachments from an email in one call
+
+**Note:** Use get_email_conversation first to see attachment metadata (filenames, sizes, types) before downloading.`;
+/**
+ * Recursively extracts attachment info (including attachmentId) from email parts
+ */
+function getAttachmentInfos(parts) {
+    if (!parts)
+        return [];
+    const attachments = [];
+    for (const part of parts) {
+        if (part.filename && part.body?.attachmentId) {
+            attachments.push({
+                filename: part.filename,
+                mimeType: part.mimeType,
+                size: part.body.size,
+                attachmentId: part.body.attachmentId,
+            });
+        }
+        if (part.parts) {
+            attachments.push(...getAttachmentInfos(part.parts));
+        }
+    }
+    return attachments;
+}
+/**
+ * Converts base64url to standard base64
+ */
+function base64UrlToBase64(data) {
+    return data.replace(/-/g, '+').replace(/_/g, '/');
+}
+/**
+ * Returns true if the MIME type represents text-based content
+ */
+function isTextMimeType(mimeType) {
+    if (mimeType.startsWith('text/'))
+        return true;
+    if (mimeType === 'application/json')
+        return true;
+    if (mimeType === 'application/xml')
+        return true;
+    if (mimeType.endsWith('+json') || mimeType.endsWith('+xml'))
+        return true;
+    return false;
+}
+/**
+ * Builds inline response with attachment content in the response text
+ */
+function buildInlineResponse(results) {
+    const outputParts = [];
+    const summaryLines = results.map((r, i) => {
+        const sizeKb = Math.round(r.size / 1024);
+        return `${i + 1}. ${r.filename} (${r.mimeType}, ${sizeKb} KB)`;
+    });
+    outputParts.push(`# Downloaded Attachments (${results.length})\n\n${summaryLines.join('\n')}`);
+    for (const result of results) {
+        const base64Data = base64UrlToBase64(result.data);
+        if (isTextMimeType(result.mimeType)) {
+            const textContent = Buffer.from(base64Data, 'base64').toString('utf-8');
+            outputParts.push(`---\n## ${result.filename}\n\n${textContent}`);
+        }
+        else {
+            outputParts.push(`---\n## ${result.filename}\n\n` +
+                `**MIME Type:** ${result.mimeType}\n` +
+                `**Encoding:** base64\n\n` +
+                `\`\`\`\n${base64Data}\n\`\`\``);
+        }
+    }
+    return {
+        content: [{ type: 'text', text: outputParts.join('\n\n') }],
+    };
+}
+/**
+ * Sanitizes a filename to prevent path traversal attacks.
+ * Strips directory components and falls back to 'attachment' if empty.
+ */
+function sanitizeFilename(filename) {
+    return basename(filename) || 'attachment';
+}
+/**
+ * Returns a unique filename, appending (1), (2), etc. if the name already exists.
+ */
+function deduplicateFilename(name, usedNames) {
+    if (!usedNames.has(name)) {
+        usedNames.add(name);
+        return name;
+    }
+    const ext = extname(name);
+    const base = name.slice(0, name.length - ext.length);
+    let counter = 1;
+    let candidate;
+    do {
+        candidate = `${base} (${counter})${ext}`;
+        counter++;
+    } while (usedNames.has(candidate));
+    usedNames.add(candidate);
+    return candidate;
+}
+/**
+ * Saves attachments to /tmp/ and returns file paths
+ */
+async function buildFileResponse(results, emailId) {
+    const safeEmailId = emailId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    const dir = join('/tmp', `gmail-attachments-${safeEmailId}`);
+    await mkdir(dir, { recursive: true });
+    const savedFiles = [];
+    const usedNames = new Set();
+    for (const result of results) {
+        const base64Data = base64UrlToBase64(result.data);
+        const buffer = Buffer.from(base64Data, 'base64');
+        const safeName = deduplicateFilename(sanitizeFilename(result.filename), usedNames);
+        const filePath = join(dir, safeName);
+        await writeFile(filePath, buffer);
+        savedFiles.push({
+            filename: result.filename,
+            path: filePath,
+            mimeType: result.mimeType,
+            size: buffer.length,
+        });
+    }
+    const outputParts = [];
+    const summaryLines = savedFiles.map((f, i) => {
+        const sizeKb = Math.round(f.size / 1024);
+        return `${i + 1}. ${f.filename} (${f.mimeType}, ${sizeKb} KB)`;
+    });
+    outputParts.push(`# Downloaded Attachments (${savedFiles.length})\n\n${summaryLines.join('\n')}`);
+    outputParts.push('## Saved Files\n');
+    for (const file of savedFiles) {
+        outputParts.push(`- **${file.filename}**: \`${file.path}\``);
+    }
+    return {
+        content: [{ type: 'text', text: outputParts.join('\n') }],
+    };
+}
+export function downloadEmailAttachmentsTool(_server, clientFactory) {
+    return {
+        name: 'download_email_attachments',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                email_id: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.email_id,
+                },
+                filename: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.filename,
+                },
+                inline: {
+                    type: 'boolean',
+                    description: PARAM_DESCRIPTIONS.inline,
+                },
+            },
+            required: ['email_id'],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = DownloadEmailAttachmentsSchema.parse(args ?? {});
+                const client = clientFactory();
+                // Fetch the email to discover attachments
+                const email = await client.getMessage(parsed.email_id, { format: 'full' });
+                const allAttachments = [];
+                // Check payload-level attachment (single-part email with attachment)
+                if (email.payload?.filename && email.payload?.body?.attachmentId) {
+                    allAttachments.push({
+                        filename: email.payload.filename,
+                        mimeType: email.payload.mimeType,
+                        size: email.payload.body.size,
+                        attachmentId: email.payload.body.attachmentId,
+                    });
+                }
+                // Check nested parts for attachments
+                allAttachments.push(...getAttachmentInfos(email.payload?.parts));
+                if (allAttachments.length === 0) {
+                    return {
+                        content: [{ type: 'text', text: 'No attachments found on this email.' }],
+                    };
+                }
+                // Filter by filename if specified
+                let targetAttachments = allAttachments;
+                if (parsed.filename) {
+                    targetAttachments = allAttachments.filter((a) => a.filename === parsed.filename);
+                    if (targetAttachments.length === 0) {
+                        const available = allAttachments.map((a) => a.filename).join(', ');
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `Attachment "${parsed.filename}" not found. Available attachments: ${available}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                }
+                // For inline mode, enforce size limit
+                if (parsed.inline) {
+                    const totalSize = targetAttachments.reduce((sum, a) => sum + a.size, 0);
+                    if (totalSize > MAX_INLINE_SIZE) {
+                        const totalMb = (totalSize / (1024 * 1024)).toFixed(1);
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `Total attachment size (${totalMb} MB) exceeds the 25 MB limit for inline mode. ` +
+                                        `Use inline=false (default) to save to files, or use the filename parameter to download individually.`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                }
+                // Download all target attachments concurrently
+                const results = await Promise.all(targetAttachments.map(async (att) => {
+                    const data = await client.getAttachment(parsed.email_id, att.attachmentId);
+                    return { ...att, data: data.data };
+                }));
+                if (parsed.inline) {
+                    return buildInlineResponse(results);
+                }
+                else {
+                    return await buildFileResponse(results, parsed.email_id);
+                }
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error downloading attachment(s): ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools.d.ts

@@ -2,7 +2,8 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ClientFactory } from './server.js';
 /**
  * Available tool groups for Gmail MCP server
- * - readonly: Read-only operations (list, get, search emails)
+ * - readonly: Read-only Gmail operations (list, get, search, download_attachments)
+ *   Note: download_email_attachments writes to local /tmp/ but does not modify mailbox state
  * - readwrite: Read and write operations (includes readonly + modify, draft)
  * - readwrite_external: External communication operations (includes readwrite + send_email)
  */

package/shared/tools.js

@@ -5,11 +5,12 @@ import { changeEmailConversationTool } from './tools/change-email-conversation.j
 import { draftEmailTool } from './tools/draft-email.js';
 import { sendEmailTool } from './tools/send-email.js';
 import { searchEmailConversationsTool } from './tools/search-email-conversations.js';
+import { downloadEmailAttachmentsTool } from './tools/download-email-attachments.js';
 const ALL_TOOL_GROUPS = ['readonly', 'readwrite', 'readwrite_external'];
 /**
  * All available tools with their group assignments
  *
- * readonly: list_email_conversations, get_email_conversation, search_email_conversations
+ * readonly: list_email_conversations, get_email_conversation, search_email_conversations, download_email_attachments
  * readwrite: all readonly tools + change_email_conversation, draft_email
  * readwrite_external: all readwrite tools + send_email (external communication)
  */
@@ -21,6 +22,10 @@ const ALL_TOOLS = [
         factory: searchEmailConversationsTool,
         groups: ['readonly', 'readwrite', 'readwrite_external'],
     },
+    {
+        factory: downloadEmailAttachmentsTool,
+        groups: ['readonly', 'readwrite', 'readwrite_external'],
+    },
     // Write tools (available in readwrite and readwrite_external)
     { factory: changeEmailConversationTool, groups: ['readwrite', 'readwrite_external'] },
     { factory: draftEmailTool, groups: ['readwrite', 'readwrite_external'] },