gmail-workspace-mcp-server 0.0.4 → 0.1.0

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.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.4",
-  "description": "MCP server for Gmail integration with service account support",
+  "version": "0.1.0",
+  "description": "MCP server for Gmail integration with OAuth2 and service account support",
   "main": "build/index.js",
   "type": "module",
   "bin": {

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
  */
@@ -108,18 +113,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;
@@ -173,16 +192,58 @@ export declare class ServiceAccountGmailClient implements IGmailClient {
     }): Promise<Email>;
     sendDraft(draftId: string): Promise<Email>;
 }
+/**
+ * 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 {
     version: string;
 }
 /**
  * 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 +283,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,8 +88,9 @@ 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();
@@ -100,14 +98,119 @@ export class ServiceAccountGmailClient {
         return sendDraft(this.baseUrl, headers, draftId);
     }
 }
+/**
+ * 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/get-email-conversation.d.ts

@@ -3,10 +3,13 @@ import { z } from 'zod';
 import type { ClientFactory } from '../server.js';
 export declare const GetEmailConversationSchema: z.ZodObject<{
     email_id: z.ZodString;
+    include_html: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     email_id: string;
+    include_html?: boolean | undefined;
 }, {
     email_id: string;
+    include_html?: boolean | undefined;
 }>;
 export declare function getEmailConversationTool(server: Server, clientFactory: ClientFactory): {
     name: string;
@@ -18,6 +21,10 @@ export declare function getEmailConversationTool(server: Server, clientFactory:
                 type: string;
                 description: string;
             };
+            include_html: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };

package/shared/tools/get-email-conversation.js

@@ -3,9 +3,12 @@ import { getHeader } from '../utils/email-helpers.js';
 const PARAM_DESCRIPTIONS = {
     email_id: 'The unique identifier of the email to retrieve. ' +
         'Obtain this from list_email_conversations or search_email_conversations.',
+    include_html: 'When true, includes the raw HTML body of the email (if available) in addition to the plain text. ' +
+        'Useful for rendering emails with original formatting, creating screenshots, or archival workflows.',
 };
 export const GetEmailConversationSchema = z.object({
     email_id: z.string().min(1).describe(PARAM_DESCRIPTIONS.email_id),
+    include_html: z.boolean().optional().describe(PARAM_DESCRIPTIONS.include_html),
 });
 const TOOL_DESCRIPTION = `Retrieve the full content of a specific email conversation by its ID.
 
@@ -13,11 +16,13 @@ Returns the complete email including headers, body content, and attachment infor
 
 **Parameters:**
 - email_id: The unique identifier of the email (required)
+- include_html: When true, includes raw HTML body in addition to plain text (optional)
 
 **Returns:**
 Full email details including:
 - Subject, From, To, Cc, Date headers
 - Full message body (plain text preferred, HTML as fallback)
+- Raw HTML body (when include_html is true and HTML content is available)
 - List of attachments (if any)
 - Labels assigned to the email
 
@@ -25,6 +30,8 @@ Full email details including:
 - Read the full content of an email after listing conversations
 - Extract specific information from an email body
 - Check attachment details
+- Render emails with original HTML formatting (use include_html: true)
+- Create email screenshots or archives with original styling
 
 **Note:** Use list_email_conversations or search_email_conversations first to get email IDs.`;
 /**
@@ -84,6 +91,22 @@ function getEmailBody(email) {
     }
     return '(No body content available)';
 }
+/**
+ * Gets the raw HTML body content from an email (if available)
+ */
+function getEmailHtmlBody(email) {
+    // Check if body is directly on payload and it's HTML
+    if (email.payload?.body?.data && email.payload.mimeType === 'text/html') {
+        return decodeBase64Url(email.payload.body.data);
+    }
+    // Try to extract HTML from parts
+    if (email.payload?.parts) {
+        const html = extractBodyContent(email.payload.parts, 'text/html');
+        if (html)
+            return html;
+    }
+    return null;
+}
 /**
  * Extracts attachment information from email parts
  */
@@ -108,7 +131,7 @@ function getAttachments(parts) {
 /**
  * Formats an email for display
  */
-function formatFullEmail(email) {
+function formatFullEmail(email, options) {
     const subject = getHeader(email, 'Subject') || '(No Subject)';
     const from = getHeader(email, 'From') || 'Unknown';
     const to = getHeader(email, 'To') || 'Unknown';
@@ -136,6 +159,26 @@ function formatFullEmail(email) {
 ## Body
 
 ${body}`;
+    // Include raw HTML body if requested
+    if (options?.includeHtml) {
+        const htmlBody = getEmailHtmlBody(email);
+        if (htmlBody) {
+            output += `
+
+## HTML Body
+
+\`\`\`html
+${htmlBody}
+\`\`\``;
+        }
+        else {
+            output += `
+
+## HTML Body
+
+(No HTML content available)`;
+        }
+    }
     if (attachments.length > 0) {
         output += `\n\n## Attachments (${attachments.length})\n`;
         attachments.forEach((att, i) => {
@@ -156,6 +199,10 @@ export function getEmailConversationTool(server, clientFactory) {
                     type: 'string',
                     description: PARAM_DESCRIPTIONS.email_id,
                 },
+                include_html: {
+                    type: 'boolean',
+                    description: PARAM_DESCRIPTIONS.include_html,
+                },
             },
             required: ['email_id'],
         },
@@ -166,7 +213,9 @@ export function getEmailConversationTool(server, clientFactory) {
                 const email = await client.getMessage(parsed.email_id, {
                     format: 'full',
                 });
-                const formattedEmail = formatFullEmail(email);
+                const formattedEmail = formatFullEmail(email, {
+                    includeHtml: parsed.include_html,
+                });
                 return {
                     content: [
                         {