search_emails

Instructions

Implementation Reference

• src/index.ts:45-59 (registration)

  Registers the 'search_emails' tool on the MCP server with zod schema for 'query' (required string) and 'maxResults' (optional int, 1-50). Handler calls searchEmails() from gmail.ts.

  server.tool(
    "search_emails",
    "Search Gmail messages with Gmail search syntax.",
    {
      query: z.string().min(1).describe("Gmail search query string."),
      maxResults: z
        .number()
        .int()
        .min(1)
        .max(50)
        .optional()
        .describe("Maximum number of emails to return. Default 10, max 50."),
    },
    async ({ query, maxResults }) => jsonResult(await searchEmails({ query, maxResults })),
  );

• src/gmail.ts:73-78 (handler)

  Exported async function searchEmails that accepts { maxResults, query } and delegates to the internal listEmails with inboxOnly: false (searching all folders/labels).

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

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

  Internal listEmails function that calls the Gmail API users.messages.list with the query and labelIds (omitted when inboxOnly=false), then fetches metadata for each message and returns summaries.

  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/index.ts:48-56 (schema)

  Zod schema for search_emails: 'query' is a required string, 'maxResults' is an optional integer between 1 and 50.

  {
    query: z.string().min(1).describe("Gmail search query string."),
    maxResults: z
      .number()
      .int()
      .min(1)
      .max(50)
      .optional()
      .describe("Maximum number of emails to return. Default 10, max 50."),