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
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>"
},
"name": "search_emails"
}
}Input 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"], ),