gmail-get-email
Retrieve a specific Gmail message using its unique message ID to access or process email content directly from the MCP Server Boilerplate environment.
Instructions
Get a specific email by message ID
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| messageId | Yes | Gmail message ID |
Implementation Reference
- src/gmail.ts:293-365 (handler)The handler function that retrieves a specific email by its message ID using the Gmail API, extracts headers and body content, handles multipart messages, truncates long bodies, formats the email details into Markdown using formatEmailToMarkdown, and returns the structured response.export async function getEmail(params: z.infer<typeof getEmailSchema>) { try { const auth = createGmailAuth(); const gmail = google.gmail({ version: "v1", auth }); const response = await gmail.users.messages.get({ userId: "me", id: params.messageId, format: "full", }); const message = response.data; const headers = message.payload?.headers || []; const getHeader = (name: string) => headers.find((h) => h.name?.toLowerCase() === name.toLowerCase()) ?.value || ""; // Extract body content let body = ""; if (message.payload?.body?.data) { body = Buffer.from(message.payload.body.data, "base64").toString(); } else if (message.payload?.parts) { // Handle multipart messages for (const part of message.payload.parts) { if (part.mimeType === "text/plain" && part.body?.data) { body = Buffer.from(part.body.data, "base64").toString(); break; } } } // Truncate body if it exceeds 30000 characters const truncatedBody = body.length > 20000 ? body.substring(0, 20000) + "\n\n[Email body truncated - content too long]" : body; const emailDetail = { id: message.id, threadId: message.threadId, from: getHeader("From"), to: getHeader("To"), cc: getHeader("Cc"), bcc: getHeader("Bcc"), subject: getHeader("Subject"), date: getHeader("Date"), body: truncatedBody, snippet: message.snippet, labelIds: message.labelIds, }; return { content: [ { type: "text" as const, text: formatEmailToMarkdown(emailDetail), }, ], }; } catch (error) { return { content: [ { type: "text" as const, text: `Error getting email: ${ error instanceof Error ? error.message : String(error) }`, }, ], }; } }
- src/gmail.ts:32-34 (schema)Zod schema defining the input parameter 'messageId' for the gmail-get-email tool.export const getEmailSchema = z.object({ messageId: z.string().describe("Gmail message ID"), });
- src/index.ts:200-207 (registration)Registers the 'gmail-get-email' tool with the MCP server, providing name, description, input schema from getEmailSchema, and handler invoking getEmail.server.tool( "gmail-get-email", "Get a specific email by message ID", getEmailSchema.shape, async (params) => { return await getEmail(params); } );
- src/gmail.ts:75-94 (helper)Helper function to format a single email object into a Markdown string, used in the getEmail handler for output presentation.function formatEmailToMarkdown(email: any): string { const date = new Date(email.date).toLocaleDateString(); const from = email.from.replace(/[<>]/g, ''); const to = email.to.replace(/[<>]/g, ''); const subject = email.subject || '(No Subject)'; let markdown = `# ${subject}\n\n`; markdown += `From: ${from} \n`; markdown += `To: ${to} \n`; if (email.cc) markdown += `CC: ${email.cc.replace(/[<>]/g, '')} \n`; if (email.bcc) markdown += `BCC: ${email.bcc.replace(/[<>]/g, '')} \n`; markdown += `Date: ${date} \n`; markdown += `Message ID: \`${email.id}\`\n\n`; if (email.body) { markdown += `---\n\n${email.body}\n`; } return markdown; }
- src/gmail.ts:134-165 (helper)Helper function to create authenticated Gmail client using OAuth2 credentials from environment variables, used by all Gmail tools including getEmail.function createGmailAuth() { const clientId = process.env.GOOGLE_CLIENT_ID; const clientSecret = process.env.GOOGLE_CLIENT_SECRET; const redirectUri = process.env.GOOGLE_REDIRECT_URI || "http://localhost:3000/oauth2callback"; if (!clientId || !clientSecret) { throw new Error( "GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are required. Run oauth-setup.js to configure." ); } const oauth2Client = new google.auth.OAuth2( clientId, clientSecret, redirectUri ); const accessToken = process.env.GOOGLE_ACCESS_TOKEN; const refreshToken = process.env.GOOGLE_REFRESH_TOKEN; if (!accessToken || !refreshToken) { throw new Error("OAuth2 tokens missing. Run oauth-setup.js to get tokens."); } oauth2Client.setCredentials({ access_token: accessToken, refresh_token: refreshToken, }); return oauth2Client; }