search_emails
Find specific emails in your Gmail inbox using Gmail's search query syntax to filter by sender, status, or content.
Instructions
Search emails using Gmail query syntax
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Gmail search query (e.g., 'is:unread', 'from:newsletter@example.com') | |
| maxResults | No | Maximum number of results (default: 10) |
Implementation Reference
- src/tools.ts:65-71 (handler)MCP tool handler for 'search_emails': validates input, invokes GmailService.searchEmails, and formats results as text response.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/gmail-service.ts:31-54 (handler)Core Gmail API implementation for searching emails and retrieving metadata (ID, subject, from, date, snippet).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:6-9 (schema)Input schema validation using Zod for the search_emails tool 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/tools.ts:50-55 (registration)Registers all MCP tools, including search_emails, by generating JSON schemas from Zod definitions with descriptions.export const getToolDefinitions = () => Object.entries(schemas).map(([name, schema]) => ({ name, description: toolDescriptions[name], inputSchema: zodToJsonSchema(schema) }));