search_emails
Search Gmail messages using standard query syntax to find specific emails based on criteria like sender, subject, or read status.
Instructions
Search emails using Gmail query syntax
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| maxResults | No | Maximum number of results (default: 10) | |
| query | Yes | Gmail search query (e.g., 'is:unread', 'from:newsletter@example.com') |
Implementation Reference
- src/tools.ts:65-71 (handler)Handler for the 'search_emails' tool: validates input, calls GmailService.searchEmails, formats and returns results as MCP content.case "search_emails": { const v = validated as z.infer<typeof schemas.search_emails>; const results = await gmailService.searchEmails(v.query, v.maxResults); return { content: [{ type: "text", text: results.length ? results.map(e => `ID: ${e.id}\nSubject: ${e.subject}\nFrom: ${e.from}\nDate: ${e.date}\nSnippet: ${e.snippet}\nGmail URL: ${gmailService.getEmailUrl(e.id)}\n`).join('---\n') : "No emails found." }] }; }
- src/tools.ts:6-9 (schema)Zod input schema for search_emails tool defining query and optional maxResults parameters.search_emails: z.object({ query: z.string().describe("Gmail search query (e.g., 'is:unread', 'from:newsletter@example.com')"), maxResults: z.number().optional().default(10).describe("Maximum number of results (default: 10)") }),
- src/gmail-service.ts:31-54 (helper)Core GmailService method implementing email search: queries Gmail API for messages matching the query and retrieves metadata (subject, from, etc.) for each.async searchEmails(query: string, maxResults = 10): Promise<EmailInfo[]> { const { data } = await this.gmail.users.messages.list({ userId: 'me', q: query, maxResults }); if (!data.messages?.length) return []; return Promise.all(data.messages.map(async (msg) => { const { data: detail } = await this.gmail.users.messages.get({ userId: 'me', id: msg.id!, format: 'metadata', metadataHeaders: ['Subject', 'From', 'To', 'Date'] }); const h = detail.payload?.headers || []; const findHeader = (name: string) => h.find(x => x.name === name)?.value || ''; return { id: msg.id!, threadId: detail.threadId, subject: findHeader('Subject'), from: findHeader('From'), to: findHeader('To'), date: findHeader('Date'), snippet: detail.snippet || '' }; })); }
- src/tools.ts:50-55 (registration)Registration function that generates MCP tool definitions for all tools including 'search_emails' from schemas and descriptions.export const getToolDefinitions = () => Object.entries(schemas).map(([name, schema]) => ({ name, description: toolDescriptions[name], inputSchema: zodToJsonSchema(schema) }));
- src/tools.ts:36-36 (registration)Tool description used during registration of search_emails.search_emails: "Search emails using Gmail query syntax",