list_emails

Instructions

Implementation Reference

• src/index.ts:17-34 (registration)

  Registers the 'list_emails' tool with the MCP server, defining input schema (maxResults, query) and delegating to listInboxEmails.

  server.tool(
    "list_emails",
    "List Gmail inbox messages. Supports maxResults and Gmail query filters.",
    {
      maxResults: z
        .number()
        .int()
        .min(1)
        .max(50)
        .optional()
        .describe("Maximum number of emails to return. Default 10, max 50."),
      query: z
        .string()
        .optional()
        .describe("Optional Gmail search query, applied within INBOX."),
    },
    async ({ maxResults, query }) => jsonResult(await listInboxEmails({ maxResults, query })),
  );

• src/gmail.ts:80-111 (handler)

  Core execution logic: calls Gmail API users.messages.list with inbox filter, then fetches metadata for each message and maps to EmailSummary objects.

  async function listEmails(options: {
    maxResults?: number;
    query?: string;
    inboxOnly: boolean;
  }): Promise<EmailSummary[]> {
    const gmail = await getGmailClient();
    const maxResults = normalizeMaxResults(options.maxResults);
  
    const response = await gmail.users.messages.list({
      userId: USER_ID,
      maxResults,
      q: options.query || undefined,
      labelIds: options.inboxOnly ? ["INBOX"] : undefined,
    });
  
    const messages = response.data.messages ?? [];
  
    return Promise.all(
      messages.map(async (message) => {
        const detail = await gmail.users.messages.get({
          userId: USER_ID,
          id: requiredId(message.id),
          format: "metadata",
          metadataHeaders: ["From", "To", "Subject", "Date"],
          fields:
            "id,threadId,snippet,labelIds,payload(headers(name,value))",
        });
  
        return toEmailSummary(detail.data);
      }),
    );
  }

• src/gmail.ts:66-71 (helper)

  Public wrapper that delegates to listEmails with inboxOnly=true.

  export async function listInboxEmails(options: {
    maxResults?: number;
    query?: string;
  }): Promise<EmailSummary[]> {
    return listEmails({ ...options, inboxOnly: true });
  }

• src/gmail.ts:7-16 (schema)

  EmailSummary type definition — the return shape of list_emails results.

  export type EmailSummary = {
    id: string;
    threadId?: string | null;
    snippet?: string | null;
    from?: string;
    to?: string;
    subject?: string;
    date?: string;
    labels?: string[] | null;
  };

• src/gmail.ts:239-245 (helper)

  Helper function that normalizes maxResults: defaults to 10, clamps between 1 and 50.

  function normalizeMaxResults(value: number | undefined): number {
    if (value === undefined || !Number.isFinite(value)) {
      return 10;
    }
  
    return Math.min(Math.max(Math.trunc(value), 1), 50);
  }