gmail-workspace-mcp-server 0.4.8 → 0.4.9

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

@@ -303,6 +303,9 @@ function createMockClient() {
                 labelIds: ['SENT'],
             };
         },
+        async getAccountEmail() {
+            return 'me@example.com';
+        },
     };
 }
 // =============================================================================

package/package.json

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

package/shared/server.d.ts

@@ -119,6 +119,13 @@ export interface IGmailClient {
         data: string;
         size: number;
     }>;
+    /**
+     * Get the email address of the Gmail account this client reads from.
+     * Used to construct account-scoped Gmail web URLs so that links open in
+     * the correct mailbox regardless of which accounts the reader happens to
+     * be signed into in their browser.
+     */
+    getAccountEmail(): Promise<string>;
 }
 /**
  * Service account credentials structure
@@ -231,6 +238,7 @@ declare abstract class BaseGmailClient implements IGmailClient {
         data: string;
         size: number;
     }>;
+    getAccountEmail(): Promise<string>;
 }
 /**
  * Gmail API client implementation using service account with domain-wide delegation

package/shared/server.js

@@ -108,6 +108,9 @@ class BaseGmailClient {
         const { getAttachment } = await import('./gmail-client/lib/get-attachment.js');
         return getAttachment(this.baseUrl, headers, messageId, attachmentId);
     }
+    async getAccountEmail() {
+        return this.getSenderEmail();
+    }
 }
 /**
  * Gmail API client implementation using service account with domain-wide delegation

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { getHeader } from '../utils/email-helpers.js';
+import { buildGmailUrl, 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.',
@@ -25,6 +25,7 @@ Full email details including:
 - Raw HTML body (when include_html is true and HTML content is available)
 - List of attachments (if any)
 - Labels assigned to the email
+- Account-scoped Gmail web URL (resolves to the correct mailbox regardless of the reader's browser session)
 
 **Use cases:**
 - Read the full content of an email after listing conversations
@@ -143,7 +144,11 @@ function formatFullEmail(email, options) {
     let output = `# Email Details
 
 **ID:** ${email.id}
-**Thread ID:** ${email.threadId}
+**Thread ID:** ${email.threadId}`;
+    if (options?.accountEmail) {
+        output += `\n**Gmail URL:** ${buildGmailUrl(options.accountEmail, email.id)}`;
+    }
+    output += `
 
 ## Headers
 **Subject:** ${subject}
@@ -210,11 +215,15 @@ export function getEmailConversationTool(server, clientFactory) {
             try {
                 const parsed = GetEmailConversationSchema.parse(args ?? {});
                 const client = clientFactory();
-                const email = await client.getMessage(parsed.email_id, {
-                    format: 'full',
-                });
+                const [email, accountEmail] = await Promise.all([
+                    client.getMessage(parsed.email_id, {
+                        format: 'full',
+                    }),
+                    client.getAccountEmail(),
+                ]);
                 const formattedEmail = formatFullEmail(email, {
                     includeHtml: parsed.include_html,
+                    accountEmail,
                 });
                 return {
                     content: [

package/shared/tools/list-email-conversations.js

@@ -37,6 +37,7 @@ A formatted list of email conversations with:
 - Sender (From)
 - Date received
 - Snippet preview
+- Account-scoped Gmail web URL (resolves to the correct mailbox regardless of the reader's browser session)
 
 **Use cases:**
 - Check recent inbox activity
@@ -113,18 +114,24 @@ export function listEmailConversationsTool(server, clientFactory) {
                         ],
                     };
                 }
-                // Fetch full details for each message
-                const emailDetails = await Promise.all(messages.map((msg) => client.getMessage(msg.id, {
-                    format: 'metadata',
-                    metadataHeaders: ['Subject', 'From', 'Date'],
-                })));
+                // Fetch full details for each message, plus the account email for
+                // building account-scoped Gmail URLs.
+                const [emailDetails, accountEmail] = await Promise.all([
+                    Promise.all(messages.map((msg) => client.getMessage(msg.id, {
+                        format: 'metadata',
+                        metadataHeaders: ['Subject', 'From', 'Date'],
+                    }))),
+                    client.getAccountEmail(),
+                ]);
                 // Sort based on sort_by parameter
                 const sortedEmails = [...emailDetails].sort((a, b) => {
                     const dateA = parseInt(a.internalDate, 10);
                     const dateB = parseInt(b.internalDate, 10);
                     return parsed.sort_by === 'recent' ? dateB - dateA : dateA - dateB;
                 });
-                const formattedEmails = sortedEmails.map(formatEmail).join('\n\n---\n\n');
+                const formattedEmails = sortedEmails
+                    .map((email) => formatEmail(email, accountEmail))
+                    .join('\n\n---\n\n');
                 return {
                     content: [
                         {

package/shared/tools/search-email-conversations.js

@@ -38,7 +38,7 @@ const TOOL_DESCRIPTION = `Search email conversations using Gmail's powerful sear
 - Use - to exclude: "subject:meeting -subject:canceled"
 
 **Returns:**
-A formatted list of matching emails with ID, Thread ID, Subject, From, Date, and snippet.
+A formatted list of matching emails with ID, Thread ID, Subject, From, Date, snippet, and an account-scoped Gmail web URL (resolves to the correct mailbox regardless of the reader's browser session).
 
 **Note:** Use get_email_conversation with an email ID to retrieve full message content.`;
 export function searchEmailConversationsTool(server, clientFactory) {
@@ -79,12 +79,18 @@ export function searchEmailConversationsTool(server, clientFactory) {
                         ],
                     };
                 }
-                // Fetch full details for each message
-                const emailDetails = await Promise.all(messages.map((msg) => client.getMessage(msg.id, {
-                    format: 'metadata',
-                    metadataHeaders: ['Subject', 'From', 'Date'],
-                })));
-                const formattedEmails = emailDetails.map(formatEmail).join('\n\n---\n\n');
+                // Fetch full details for each message, plus the account email for
+                // building account-scoped Gmail URLs.
+                const [emailDetails, accountEmail] = await Promise.all([
+                    Promise.all(messages.map((msg) => client.getMessage(msg.id, {
+                        format: 'metadata',
+                        metadataHeaders: ['Subject', 'From', 'Date'],
+                    }))),
+                    client.getAccountEmail(),
+                ]);
+                const formattedEmails = emailDetails
+                    .map((email) => formatEmail(email, accountEmail))
+                    .join('\n\n---\n\n');
                 return {
                     content: [
                         {

package/shared/tools/send-email.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { getHeader } from '../utils/email-helpers.js';
+import { buildGmailUrl, getHeader } from '../utils/email-helpers.js';
 import { requestConfirmation, createConfirmationSchema, readElicitationConfig, } from '@pulsemcp/mcp-elicitation';
 const PARAM_DESCRIPTIONS = {
     to: 'Recipient email address(es). For multiple recipients, separate with commas.',
@@ -180,11 +180,15 @@ export function sendEmailTool(server, clientFactory) {
                 // Option 2: Send a draft
                 if (parsed.from_draft_id) {
                     const sentEmail = await client.sendDraft(parsed.from_draft_id);
+                    const accountEmail = await client.getAccountEmail();
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: `Draft sent successfully!\n\n**Message ID:** ${sentEmail.id}\n**Thread ID:** ${sentEmail.threadId}\n\nThe draft has been sent and removed from Drafts.`,
+                                text: `Draft sent successfully!\n\n**Message ID:** ${sentEmail.id}\n` +
+                                    `**Thread ID:** ${sentEmail.threadId}\n` +
+                                    `**Gmail URL:** ${buildGmailUrl(accountEmail, sentEmail.id)}\n\n` +
+                                    `The draft has been sent and removed from Drafts.`,
                             },
                         ],
                     };
@@ -220,7 +224,10 @@ export function sendEmailTool(server, clientFactory) {
                     inReplyTo,
                     references,
                 });
-                let responseText = `Email sent successfully!\n\n**Message ID:** ${sentEmail.id}\n**Thread ID:** ${sentEmail.threadId}`;
+                const accountEmail = await client.getAccountEmail();
+                let responseText = `Email sent successfully!\n\n**Message ID:** ${sentEmail.id}\n` +
+                    `**Thread ID:** ${sentEmail.threadId}\n` +
+                    `**Gmail URL:** ${buildGmailUrl(accountEmail, sentEmail.id)}`;
                 if (parsed.thread_id) {
                     responseText += '\n\nThis email was sent as a reply in an existing conversation.';
                 }

package/shared/utils/email-helpers.d.ts

@@ -4,6 +4,22 @@ import type { Email } from '../types.js';
  */
 export declare function getHeader(email: Email, headerName: string): string | undefined;
 /**
- * Formats an email for display in tool output
+ * Builds an account-scoped Gmail web URL for a given message.
+ *
+ * Uses the `/mail/u/<account-email>/#inbox/<messageId>` path form so the link
+ * opens in the correct mailbox regardless of which accounts the reader is
+ * signed into in their browser. The user-INDEX form `/mail/u/0/` would
+ * otherwise open whichever account happens to be at index 0 in the reader's
+ * browser session, which is rarely the impersonated/OAuth account this
+ * server reads from.
+ *
+ * Gmail also accepts `?authuser=<email>` as a query-parameter fallback.
  */
-export declare function formatEmail(email: Email): string;
+export declare function buildGmailUrl(accountEmail: string, messageId: string): string;
+/**
+ * Formats an email for display in tool output.
+ *
+ * When `accountEmail` is provided, an account-scoped Gmail web URL is
+ * appended so the user can click through to the correct mailbox.
+ */
+export declare function formatEmail(email: Email, accountEmail?: string): string;

package/shared/utils/email-helpers.js

@@ -6,17 +6,39 @@ export function getHeader(email, headerName) {
         ?.value;
 }
 /**
- * Formats an email for display in tool output
+ * Builds an account-scoped Gmail web URL for a given message.
+ *
+ * Uses the `/mail/u/<account-email>/#inbox/<messageId>` path form so the link
+ * opens in the correct mailbox regardless of which accounts the reader is
+ * signed into in their browser. The user-INDEX form `/mail/u/0/` would
+ * otherwise open whichever account happens to be at index 0 in the reader's
+ * browser session, which is rarely the impersonated/OAuth account this
+ * server reads from.
+ *
+ * Gmail also accepts `?authuser=<email>` as a query-parameter fallback.
  */
-export function formatEmail(email) {
+export function buildGmailUrl(accountEmail, messageId) {
+    return `https://mail.google.com/mail/u/${encodeURIComponent(accountEmail)}/#inbox/${messageId}`;
+}
+/**
+ * Formats an email for display in tool output.
+ *
+ * When `accountEmail` is provided, an account-scoped Gmail web URL is
+ * appended so the user can click through to the correct mailbox.
+ */
+export function formatEmail(email, accountEmail) {
     const subject = getHeader(email, 'Subject') || '(No Subject)';
     const from = getHeader(email, 'From') || 'Unknown';
     const date = getHeader(email, 'Date') || 'Unknown date';
     const snippet = email.snippet || '';
-    return `**ID:** ${email.id}
+    let output = `**ID:** ${email.id}
 **Thread ID:** ${email.threadId}
 **Subject:** ${subject}
 **From:** ${from}
 **Date:** ${date}
 **Preview:** ${snippet}`;
+    if (accountEmail) {
+        output += `\n**Gmail URL:** ${buildGmailUrl(accountEmail, email.id)}`;
+    }
+    return output;
 }