search_emails
Find specific emails in IMAP mailboxes using search queries to locate messages based on content, sender, date, or other criteria.
Instructions
Search emails with query
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (IMAP SEARCH syntax or text) | |
| mailbox | No | Mailbox name (default: current) | |
| limit | No | Max results (default: 50) |
Implementation Reference
- src/imap_mcp/imap_client.py:489-513 (handler)The actual implementation of the search_emails functionality in the IMAP client class.
def search_emails( self, query: str, mailbox: Optional[str] = None, limit: int = 50 ) -> list[EmailHeader]: """Search emails with query (IMAP SEARCH syntax or text).""" self._ensure_connected() if mailbox: self.select_mailbox(mailbox) elif not self.current_mailbox: self.select_mailbox("INBOX") # Try to parse as IMAP search criteria, fallback to TEXT search try: if any(kw in query.upper() for kw in ["FROM", "TO", "SUBJECT", "BODY", "ALL", "UNSEEN"]): uids = self.client.search(query.split()) else: uids = self.client.search(["TEXT", query]) except Exception: uids = self.client.search(["TEXT", query]) uids = sorted(uids, reverse=True)[:limit] if not uids: return [] messages = self.client.fetch(uids, ["ENVELOPE", "FLAGS", "RFC822.SIZE"]) return [self._parse_email_header(uid, data) for uid, data in messages.items()] - src/imap_mcp/server.py:174-183 (registration)Registration of the search_emails tool within the MCP server definition.
make_tool( "search_emails", "Search emails with query", { "query": {"type": "string", "description": "Search query (IMAP SEARCH syntax or text)"}, "mailbox": {"type": "string", "description": "Mailbox name (default: current)"}, "limit": {"type": "number", "description": "Max results (default: 50)"}, }, ["query"], ),