listEmails

Instructions

Implementation Reference

• src/index.ts:82-142 (handler)

  The handler function that executes the listEmails tool logic - fetches messages from Gmail API and parses them.

  case "listEmails": {
    if (!GMAIL_API_KEY) {
      return { content: [{ type: "text", text: "API Key not set." }] };
    }
  
    try {
      const { query, maxResults } = request.params.arguments || {};
  
      const queryParam = query
        ? `?q=${encodeURIComponent(query as string)}&maxResults=${maxResults}`
        : `?maxResults=${maxResults}`;
  
      const messageListResponse = await fetch(
        `https://gmail.googleapis.com/gmail/v1/users/${GMAIL_USER_ID}/messages${queryParam}`,
        { 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) {
        return { content: [{ type: "text", text: "No messages found." }] };
      }
  
      const emailMessages = [];
  
      for (const message of messageList.messages) {
        const messageId = message.id;
        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();
        emailMessages.push(await parseMessage(fullMessage));
      }
  
      return {
        content: [{ type: "text", text: JSON.stringify(emailMessages) }],
      };
    } catch (error: any) {
      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
    }
  }

• src/index.ts:28-42 (schema)

  Zod schema defining the input parameters for the listEmails tool (query and maxResults).

  const ListEmailsSchema = z.object({
    query: z
      .string()
      .describe(
        "The search query to filter emails. Use 'in:inbox','in:spam' 'in:unread', 'in:starred', 'in:sent', 'in:all', 'in:category_social', 'in:category_promotions', 'in:category_updates', 'in:category_forums', 'in:primary' or 'in:draft' to filter by label."
      )
      .optional()
      .default("in:inbox"),
  
    maxResults: z
      .number()
      .optional()
      .describe("The maximum number of emails to retrieve.")
      .default(3),
  });

• src/index.ts:60-64 (registration)

  Tool registration in the ListToolsRequestSchema handler, exposing listEmails to MCP clients.

    name: "listEmails",
    description:
      "List emails from Gmail with subject, sender, and body in Markdown format. Optionally filter and summarize results.",
    inputSchema: zodToJsonSchema(ListEmailsSchema),
  },

• src/index.ts:258-299 (helper)

  Helper function used by listEmails to parse Gmail message payload and extract subject, sender, and body.

  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,
    };
  }