gmail-workspace-mcp-server 0.1.0 → 0.1.2

package/README.md

@@ -48,24 +48,22 @@ Use this for personal `@gmail.com` accounts or any Google account without Worksp
 
 #### Getting a Refresh Token
 
-Run the one-time setup script from a clone of the repository:
+Run the built-in setup command:
 
 ```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>
+npx gmail-workspace-mcp-server oauth-setup <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
+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:
 
 ```bash
-PORT=3001 npx tsx scripts/oauth-setup.ts <client_id> <client_secret>
+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.

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

@@ -5,12 +5,31 @@ import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { createMCPServer } from '../shared/index.js';
 import { logServerStart, logError, logWarning } from '../shared/logging.js';
+import { runOAuthSetup } from './oauth-setup.js';
 // Read version from package.json
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageJsonPath = join(__dirname, '..', 'package.json');
 const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
 const VERSION = packageJson.version;
 // =============================================================================
+// CLI SUBCOMMAND HANDLING
+// =============================================================================
+// Check for subcommands before env validation (e.g., "oauth-setup")
+const subcommand = process.argv[2];
+if (subcommand === 'oauth-setup') {
+    runOAuthSetup(process.argv.slice(3)).catch((error) => {
+        console.error('Error:', error.message);
+        process.exit(1);
+    });
+}
+else {
+    // Run the MCP server (default behavior)
+    main().catch((error) => {
+        logError('main', error);
+        process.exit(1);
+    });
+}
+// =============================================================================
 // ENVIRONMENT VALIDATION
 // =============================================================================
 function validateEnvironment() {
@@ -45,7 +64,7 @@ function validateEnvironment() {
         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('  npx gmail-workspace-mcp-server oauth-setup <client_id> <client_secret>');
         console.error('\n======================================================\n');
         process.exit(1);
     }
@@ -83,7 +102,7 @@ function validateEnvironment() {
     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  Setup: Run `npx gmail-workspace-mcp-server oauth-setup <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');
@@ -123,8 +142,3 @@ async function main() {
     await server.connect(transport);
     logServerStart('Gmail');
 }
-// Run the server
-main().catch((error) => {
-    logError('main', error);
-    process.exit(1);
-});

package/build/oauth-setup.d.ts

@@ -0,0 +1,14 @@
+/**
+ * OAuth2 setup flow for obtaining a Gmail refresh token.
+ *
+ * This module is invoked as a CLI subcommand:
+ *   npx gmail-workspace-mcp-server oauth-setup <client_id> <client_secret>
+ *
+ * It starts a local HTTP server, opens the Google OAuth consent flow,
+ * and prints the resulting refresh token for use in MCP server configuration.
+ */
+/**
+ * Run the OAuth2 setup flow.
+ * @param args - CLI arguments after "oauth-setup" (i.e., [client_id, client_secret])
+ */
+export declare function runOAuthSetup(args: string[]): Promise<void>;

package/build/oauth-setup.js

@@ -0,0 +1,135 @@
+/**
+ * OAuth2 setup flow for obtaining a Gmail refresh token.
+ *
+ * This module is invoked as a CLI subcommand:
+ *   npx gmail-workspace-mcp-server oauth-setup <client_id> <client_secret>
+ *
+ * It starts a local HTTP server, opens the Google OAuth consent flow,
+ * and prints the resulting refresh token for use in MCP server configuration.
+ */
+import http from 'node:http';
+import { OAuth2Client } from 'google-auth-library';
+const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+const 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',
+];
+function waitForCallback(port) {
+    return new Promise((resolve, reject) => {
+        const server = http.createServer((req, res) => {
+            if (!req.url?.startsWith('/callback')) {
+                res.writeHead(404);
+                res.end('Not found');
+                return;
+            }
+            const url = new URL(req.url, `http://localhost:${port}`);
+            const code = url.searchParams.get('code');
+            const error = url.searchParams.get('error');
+            if (error) {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end('<html><body><h1>Authorization Failed</h1><p>You can close this window.</p></body></html>');
+                server.close();
+                reject(new Error(`OAuth error: ${error}`));
+                return;
+            }
+            if (!code) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end('<html><body><h1>Missing Code</h1><p>No authorization code received.</p></body></html>');
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end('<html><body><h1>Authorization Successful!</h1><p>You can close this window and return to the terminal.</p></body></html>');
+            clearTimeout(timeout);
+            server.close();
+            resolve(code);
+        });
+        const timeout = setTimeout(() => {
+            console.error('\nTimeout: No callback received within 5 minutes. Exiting.');
+            server.close();
+            reject(new Error('OAuth callback timeout - no response within 5 minutes'));
+        }, CALLBACK_TIMEOUT_MS);
+        server.listen(port, () => {
+            // Server is listening
+        });
+        server.on('error', (err) => {
+            clearTimeout(timeout);
+            if (err.code === 'EADDRINUSE') {
+                reject(new Error(`Port ${port} is already in use. Please free it or set PORT env var.`));
+            }
+            else {
+                reject(err);
+            }
+        });
+    });
+}
+/**
+ * Run the OAuth2 setup flow.
+ * @param args - CLI arguments after "oauth-setup" (i.e., [client_id, client_secret])
+ */
+export async function runOAuthSetup(args) {
+    const clientId = args[0] || process.env.GMAIL_OAUTH_CLIENT_ID;
+    const clientSecret = args[1] || process.env.GMAIL_OAUTH_CLIENT_SECRET;
+    if (!clientId || !clientSecret) {
+        console.error('Usage: npx gmail-workspace-mcp-server oauth-setup <client_id> <client_secret>');
+        console.error('');
+        console.error('Or set environment variables:');
+        console.error('  GMAIL_OAUTH_CLIENT_ID=... GMAIL_OAUTH_CLIENT_SECRET=... npx gmail-workspace-mcp-server oauth-setup');
+        console.error('');
+        console.error('Get your OAuth2 credentials from:');
+        console.error('  https://console.cloud.google.com/apis/credentials');
+        process.exit(1);
+    }
+    const port = parseInt(process.env.PORT || '3000', 10);
+    const redirectUri = `http://localhost:${port}/callback`;
+    const oauth2Client = new OAuth2Client(clientId, clientSecret, redirectUri);
+    const authorizeUrl = oauth2Client.generateAuthUrl({
+        access_type: 'offline',
+        scope: SCOPES,
+        prompt: 'consent', // Force consent to ensure refresh token is returned
+    });
+    console.log('\n=== Gmail OAuth2 Setup ===\n');
+    console.log('1. Open this URL in your browser:\n');
+    console.log(`   ${authorizeUrl}\n`);
+    console.log('2. Sign in and authorize the application');
+    console.log(`3. You will be redirected to localhost:${port}/callback\n`);
+    console.log('Waiting for callback (5 minute timeout)...\n');
+    const code = await waitForCallback(port);
+    console.log('Authorization code received! Exchanging for tokens...\n');
+    const { tokens } = await oauth2Client.getToken(code);
+    if (!tokens.refresh_token) {
+        console.error('ERROR: No refresh token received.');
+        console.error('');
+        console.error('This can happen if:');
+        console.error('  - You previously authorized this app (revoke access at https://myaccount.google.com/permissions)');
+        console.error('  - The OAuth consent screen is still in "Testing" mode');
+        console.error('');
+        console.error('Try revoking access and running this script again.');
+        process.exit(1);
+    }
+    console.log('=== Setup Complete ===\n');
+    console.log('Add these environment variables to your MCP server configuration:\n');
+    console.log(`  GMAIL_OAUTH_CLIENT_ID=${clientId}`);
+    console.log(`  GMAIL_OAUTH_CLIENT_SECRET=${clientSecret}`);
+    console.log(`  GMAIL_OAUTH_REFRESH_TOKEN=${tokens.refresh_token}`);
+    console.log('');
+    console.log('SECURITY NOTE: Keep your refresh token secure. Anyone with this token and your');
+    console.log('client credentials can access your Gmail account.\n');
+    console.log('Example Claude Desktop config:\n');
+    console.log(JSON.stringify({
+        mcpServers: {
+            gmail: {
+                command: 'npx',
+                args: ['gmail-workspace-mcp-server'],
+                env: {
+                    GMAIL_OAUTH_CLIENT_ID: clientId,
+                    GMAIL_OAUTH_CLIENT_SECRET: clientSecret,
+                    GMAIL_OAUTH_REFRESH_TOKEN: tokens.refresh_token,
+                },
+            },
+        },
+    }, null, 2));
+    console.log('');
+    process.exit(0);
+}

package/package.json

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

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/server.d.ts

@@ -96,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
@@ -191,6 +198,10 @@ declare abstract class BaseGmailClient 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

package/shared/server.js

@@ -97,6 +97,11 @@ class BaseGmailClient {
         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

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'] },