gmail-mcp MCP Server

Instructions

Implementation Reference

• src/index.ts:143-202 (handler)

  The getEmailContent tool handler that retrieves full email content. It validates the emailIndex parameter, fetches the list of messages to find the message at the specified index, retrieves the full message content from Gmail API, parses it, and returns the result.
  case "getEmailContent": { if (!GMAIL_API_KEY) { return { content: [{ type: "text", text: "API Key not set." }] }; } try { const { emailIndex } = EmailIndexSchema.parse(request.params.arguments); // 1. Get List of Message IDs (up to the requested index) const messageListResponse = await fetch( `https://gmail.googleapis.com/gmail/v1/users/${GMAIL_USER_ID}/messages?maxResults=${emailIndex}`, { headers: { Authorization: `Bearer ${GMAIL_API_KEY}` } } ); if (!messageListResponse.ok) { const errorData = await messageListResponse.json(); const errorMessage = errorData.error?.message || messageListResponse.statusText; return { content: [{ type: "text", text: `Error: ${errorMessage}` }], }; } const messageList = await messageListResponse.json(); if (!messageList.messages || messageList.messages.length < emailIndex) { return { content: [ { type: "text", text: "Email not found at the specified index." }, ], }; } const messageId = messageList.messages[emailIndex - 1].id; // Get the ID at the requested index // 2. Get Full Message Content const messageResponse = await fetch( `https://gmail.googleapis.com/gmail/v1/users/${GMAIL_USER_ID}/messages/${messageId}?format=full`, { headers: { Authorization: `Bearer ${GMAIL_API_KEY}` } } ); if (!messageResponse.ok) { const errorData = await messageResponse.json(); const errorMessage = errorData.error?.message || messageResponse.statusText; return { content: [{ type: "text", text: `Error: ${errorMessage}` }], }; } const fullMessage = await messageResponse.json(); const emailContent = await parseMessage(fullMessage); return { content: [{ type: "text", text: JSON.stringify(emailContent) }], }; } catch (error: any) { return { content: [{ type: "text", text: `Error: ${error.message}` }] }; } }
• src/index.ts:65-69 (registration)

  Tool registration in the MCP server that defines the getEmailContent tool with its name, description, and input schema.
  { name: "getEmailContent", description: "Retrieve the full content of an email from Gmail.", inputSchema: zodToJsonSchema(EmailIndexSchema), },
• src/index.ts:18-20 (schema)

  Zod schema definition for the getEmailContent tool parameters, validating the emailIndex input.
  const EmailIndexSchema = z.object({ emailIndex: z.number().describe("The index of the email to retrieve."), });
• src/index.ts:258-299 (helper)

  Helper function parseMessage that extracts and decodes the email subject, sender, and body from the Gmail API message format, handling both multipart and simple messages.
  async function parseMessage(message: { payload: { headers: { name: string; value: string }[]; parts: { mimeType: string; body: { data: WithImplicitCoercion<string> } }[]; body: { data: WithImplicitCoercion<string> }; }; id: string; }) { const headers = message.payload.headers; const subject = headers.find( (header: { name: string }) => header.name === "Subject" )?.value; const from = headers.find( (header: { name: string }) => header.name === "From" )?.value; let body = ""; if (message.payload.parts) { const textPart = message.payload.parts.find( (part) => part.mimeType === "text/plain" ); if (textPart) { body = Buffer.from(textPart.body.data, "base64").toString("utf-8"); } else { const htmlPart = message.payload.parts.find( (part) => part.mimeType === "text/html" ); if (htmlPart) { body = Buffer.from(htmlPart.body.data, "base64").toString("utf-8"); } } } else if (message.payload.body.data) { body = Buffer.from(message.payload.body.data, "base64").toString("utf-8"); } return { id: message.id, subject: subject, from: from, body: body, }; }