MCP Tools Reference

MoMail exposes four MCP tools for email interaction. Each tool accepts specific parameters and returns structured data.

search_emails

Search emails using natural language queries or specific filters.

Description

Uses vector similarity search to find emails matching your query. Supports semantic matching, so you can search by meaning rather than exact keywords.

Parameters

{
  "query": "Q4 budget discussions from Sarah",
  "mailbox_id": "mb_abc123",
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "budget",
  "date_from": "2024-01-01",
  "date_to": "2024-01-31",
  "limit": 10,
  "offset": 0
}

Parameter	Type	Required	Description
query	string	Yes	Natural language search query
mailbox_id	string	No	Filter to specific mailbox
from	string	No	Filter by sender email
to	string	No	Filter by recipient email
subject	string	No	Filter by subject (partial match)
date_from	string	No	Start date (YYYY-MM-DD)
date_to	string	No	End date (YYYY-MM-DD)
limit	number	No	Max results (1-100, default: 10)
offset	number	No	Results to skip (default: 0)

Returns

{
  "results": [
    {
      "email_id": "msg_abc123",
      "subject": "Q4 Budget Review",
      "from": "[email protected]",
      "date": "2024-01-15T10:30:00.000Z",
      "snippet": "Hi team, I wanted to discuss our Q4 budget allocation...",
      "score": 0.92
    }
  ],
  "total": 45
}

Example Usage

User: Find emails about the project deadline from last week

Claude: I'll search for emails about project deadlines from the past week.

[Tool Call: search_emails]
- query: "project deadline"
- date_from: "2024-01-08"
- date_to: "2024-01-15"
- limit: 10

Results:
- "Project Timeline Update" from [email protected] (score: 0.89)
- "Re: Q1 Deliverables" from [email protected] (score: 0.85)
- "Urgent: Schedule Changes" from [email protected] (score: 0.82)

get_email

Retrieve a specific email by its ID.

Description

Fetches complete email details including body content and attachment metadata.

Parameters

{
  "email_id": "msg_abc123"
}

Parameter	Type	Required	Description
email_id	string	Yes	The email message ID

Returns

{
  "email": {
    "email_id": "msg_abc123",
    "subject": "Q4 Budget Review",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "cc": ["[email protected]"],
    "date": "2024-01-15T10:30:00.000Z",
    "body_text": "Hi team, I wanted to discuss our Q4 budget allocation...",
    "has_attachments": true,
    "attachment_ids": ["att_xyz789"]
  }
}

Example Usage

User: Show me the full content of the first email

Claude: I'll retrieve the complete email for you.

[Tool Call: get_email]
- email_id: "msg_abc123"

The email from [email protected]:

Subject: Q4 Budget Review
Date: January 15, 2024 at 10:30 AM

Hi team, I wanted to discuss our Q4 budget allocation and get your feedback on the proposed changes...

This email has 1 attachment.

get_email_thread

Retrieve all emails in a conversation thread.

Description

Gets the complete thread including all messages in chronological order. Useful for understanding the full context of a conversation.

Parameters

{
  "thread_id": "thread_abc123",
  "include_body": true
}

Parameter	Type	Required	Description
thread_id	string	Yes	The thread identifier
include_body	boolean	No	Include full body text (default: true)

Returns

{
  "thread_id": "thread_abc123",
  "thread": [
    {
      "email_id": "msg_001",
      "subject": "Q4 Budget Review",
      "from": "[email protected]",
      "to": ["[email protected]"],
      "date": "2024-01-15T10:30:00.000Z",
      "body_text_snippet": "Hi team, I wanted to discuss..."
    },
    {
      "email_id": "msg_002",
      "subject": "Re: Q4 Budget Review",
      "from": "[email protected]",
      "to": ["[email protected]", "[email protected]"],
      "date": "2024-01-15T11:45:00.000Z",
      "body_text_snippet": "Thanks Sarah, here are my thoughts..."
    }
  ]
}

Example Usage

User: Show me the entire conversation about the budget

Claude: I'll retrieve all emails in this thread.

[Tool Call: get_email_thread]
- thread_id: "thread_abc123"
- include_body: true

This thread contains 4 messages:

1. Jan 15, 10:30 AM - Sarah: "Q4 Budget Review" (original)
2. Jan 15, 11:45 AM - John: "Re: Q4 Budget Review"
3. Jan 15, 2:15 PM - Sarah: "Re: Q4 Budget Review"
4. Jan 16, 9:00 AM - Mike: "Re: Q4 Budget Review"

list_mailboxes

List all mailboxes for the authenticated user.

Description

Returns mailbox details including email address, status, and email counts.

Parameters

This tool accepts an empty object {} as parameters.

Returns

{
  "mailboxes": [
    {
      "mailbox_id": "mb_abc123",
      "email_address": "[email protected]",
      "domain": "example.com",
      "status": "active",
      "email_count": 152,
      "last_email_date": "2024-01-15T10:30:00.000Z"
    },
    {
      "mailbox_id": "mb_xyz789",
      "email_address": "[email protected]",
      "domain": "company.com",
      "status": "active",
      "email_count": 89,
      "last_email_date": "2024-01-14T16:20:00.000Z"
    }
  ]
}

Example Usage

User: What mailboxes do I have?

Claude: Let me check your mailboxes.

[Tool Call: list_mailboxes]

You have 2 active mailboxes:

1. [email protected]
   - 152 emails
   - Last email: January 15, 2024

2. [email protected]
   - 89 emails
   - Last email: January 14, 2024

Tool Selection Guide

Use Case	Recommended Tool
Find emails matching a description	search_emails
Read a specific email’s content	get_email
See full conversation history	get_email_thread
Check which mailboxes exist	list_mailboxes
Search within a date range	search_emails with date filters
Find emails from a specific person	search_emails with from filter

Parameter Best Practices

1. Use natural language in query: Instead of keywords, describe what you are looking for
2. Combine filters: Use multiple filters together for precise results
3. Start with small limit: Begin with 10 results, increase if needed
4. Use dates for recency: Add date_from and date_to to find recent emails

Error Handling

Tools may return errors in these cases:

• Invalid parameters: The request parameters failed validation
• Email not found: The specified email_id does not exist
• Thread not found: The specified thread_id does not exist
• Rate limit exceeded: Too many requests in the current window
• Authentication failed: Invalid or expired API key