gmail_search
Search your Gmail inbox using Gmail's query syntax to find emails by sender, subject, date, attachments, or read status.
Instructions
Search emails using Gmail query syntax. Returns a list of matching emails with subject, sender, date, and snippet. Use Gmail search operators like 'from:', 'to:', 'subject:', 'is:unread', 'has:attachment', 'after:', 'before:'.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Gmail search query string. Examples: 'from:john@example.com', 'subject:meeting is:unread', 'after:2024/01/01 has:attachment'. | |
| max_results | No | Maximum number of emails to return. Must be between 1 and 100. Default is 20. |
Implementation Reference
- src/mcp_gmail/server_old.py:47-66 (registration)Registration of the gmail_search tool including its schema definition within the list_tools() function.
Tool( name="gmail_search", description="Search emails using Gmail query syntax or natural language. " "Examples: 'from:john@example.com', 'subject:meeting', 'is:unread'", inputSchema={ "type": "object", "properties": { "query": { "type": "string", "description": "Gmail search query or natural language search", }, "max_results": { "type": "integer", "description": "Maximum number of results (default: 20, max: 100)", "default": 20, }, }, "required": ["query"], }, ), - src/mcp_gmail/server_old.py:295-304 (handler)Handler implementation in call_tool() that parses arguments, calls GmailClient.search_emails(), formats results with _format_email_list, and returns TextContent.
if name == "gmail_search": query = arguments.get("query", "") max_results = arguments.get("max_results", 20) results = await client.search_emails(query, max_results) return [ TextContent( type="text", text=_format_email_list(results), ) ] - GmailClient.search_emails method: converts tool parameters to SearchQuery object and delegates to list_emails() which performs the actual Gmail API search.
async def search_emails(self, query: str, max_results: int = 20) -> list[EmailSummary]: """Simple search interface for natural language queries.""" search = SearchQuery(query=query, max_results=max_results) return await self.list_emails(search) - src/mcp_gmail/server_old.py:730-749 (helper)Helper function to format the list of EmailSummary objects returned from search into a readable text response.
def _format_email_list(emails: list) -> str: """Format email list for display.""" if not emails: return "No emails found." lines = [f"Found {len(emails)} email(s):\n"] for email in emails: status = "📬" if not email.is_read else "📭" star = "⭐" if email.is_starred else "" attachment = "📎" if email.has_attachments else "" categories = f" [{', '.join(email.categories)}]" if email.categories else "" lines.append( f"{status}{star}{attachment} **{email.subject}**{categories}\n" f" From: {email.sender}\n" f" Date: {email.date.strftime('%Y-%m-%d %H:%M')}\n" f" ID: `{email.id}`\n" f" {email.snippet[:100]}...\n" ) return "\n".join(lines)