MCP Server Documentation

Give your AI assistant access to your email

Search, browse, and read your Gmail from Claude, Cursor, Windsurf, VS Code, and any MCP-compatible client.

https://mcp.app.emailzap.co/mcp

What You Can Do

🔍

Search Emails

Ask natural language questions across all your Gmail accounts. AI-powered semantic search with relevance ranking.

📥

Browse Inbox

Filter by label, date, importance, or specific accounts. Paginated results with read status and attachments.

💬

Read Threads

Get complete email conversations with all replies, full content, and attachment details.

Prerequisites

Setup

Choose your AI client below for setup instructions.

No API key needed. Claude handles authentication automatically via OAuth.
  1. Open claude.ai
  2. Go to Customize → Connectors → Add custom connector
  3. Enter Name: "EmailZap" and URL: https://mcp.app.emailzap.co/mcp
  4. Click Add — you'll be redirected to sign in with Google
  5. Authorize EmailZap to access your Gmail
  6. Done — ask Claude to search your emails

Tools Reference

Three read-only tools for searching, browsing, and reading your emails.

search_emailsSearch Emails

AI-powered semantic search across all connected email accounts. Returns an AI-generated answer and matching emails.

ParameterTypeRequiredDescription
querystringYesNatural language search query
Example prompts
“Find invoices from Amazon in the last month”“Emails from John about the Q4 budget”“Any emails mentioning the project deadline”
list_emailsList Emails

Browse your unified inbox with filtering and pagination. Returns threads from all connected accounts.

ParameterTypeRequiredDescription
pageintegerNoPage number (default: 1)
page_sizeintegerNoEmails per page (default: 10, max: 50)
labelstringNoGmail label (e.g. INBOX, STARRED, IMPORTANT)
show_important_onlybooleanNoShow only important emails
from_datestringNoFilter from date (ISO 8601)
to_datestringNoFilter to date (ISO 8601)
account_emailslistNoFilter to specific connected accounts
Example prompts
“Show me my latest 10 emails”“Show me starred emails from this week”“List emails from my work account only”
get_emailGet Email Thread

Retrieve all messages in an email thread including replies, with full content and attachments info.

ParameterTypeRequiredDescription
thread_idstringYesThread ID from a search or list result
Example prompts
“Show me the full thread for that email”“Get all replies in that conversation”

Working Examples

Real examples showing prompts and JSON responses from the API.

1. Search for invoicessearch_emails
Prompt: “Find invoices from Amazon in the last month”
{
  "status": "success",
  "answer": "I found 3 invoices from Amazon in the last month totaling $247.89.",
  "related_emails": [
    {
      "message_id": "18e3a1b2c3d4e5f6",
      "thread_id": "18e3a1b2c3d4e5f6",
      "subject": "Your Amazon.com order #112-3456789-0123456",
      "sender_email": "auto-confirm@amazon.com",
      "received_at": "2026-03-15T10:23:00Z",
      "user_email": "user@gmail.com",
      "link": "https://mail.google.com/mail/u/user@gmail.com/#inbox/18e3a1b2c3d4e5f6",
      "body_snippet": "Your order of Wireless Mouse has been confirmed. Total: $29.99...",
      "relevance_score": 0.95
    },
    {
      "message_id": "18e2b3c4d5e6f7a8",
      "thread_id": "18e2b3c4d5e6f7a8",
      "subject": "Your Amazon.com order #112-7890123-4567890",
      "sender_email": "auto-confirm@amazon.com",
      "received_at": "2026-03-08T14:45:00Z",
      "user_email": "user@gmail.com",
      "link": "https://mail.google.com/mail/u/user@gmail.com/#inbox/18e2b3c4d5e6f7a8",
      "body_snippet": "Your order of USB-C Hub has been confirmed. Total: $49.95...",
      "relevance_score": 0.92
    }
  ],
  "total_emails_found": 3,
  "accounts_with_results": 1,
  "most_recent_email_date": "2026-03-15T10:23:00Z"
}
2. Browse starred emailslist_emails
Prompt: “Show me my 5 most recent starred emails”
{
  "status": "success",
  "count": 23,
  "page": 1,
  "page_size": 5,
  "results": [
    {
      "message_id": "18e4f1a2b3c4d5e6",
      "thread_id": "18e4f1a2b3c4d5e6",
      "subject": "Q2 Planning Meeting - Agenda",
      "sender_email": "manager@company.com",
      "sender_name": "Jane Smith",
      "received_at": "2026-03-24T16:30:00Z",
      "snippet": "Hi team, please review the attached agenda before our meeting...",
      "is_read": true,
      "is_starred": true,
      "is_important": true,
      "labels": ["INBOX", "STARRED", "IMPORTANT"],
      "has_attachments": true,
      "to": [{"name": "Team", "email": "user@gmail.com"}],
      "cc": [],
      "bcc": [],
      "account_email": "user@gmail.com"
    },
    {
      "message_id": "18e3e2b3c4d5e6f7",
      "thread_id": "18e3e2b3c4d5e6f7",
      "subject": "Flight Confirmation - NYC to SFO",
      "sender_email": "noreply@airline.com",
      "sender_name": "United Airlines",
      "received_at": "2026-03-22T11:15:00Z",
      "snippet": "Your flight UA 456 on April 2nd has been confirmed...",
      "is_read": true,
      "is_starred": true,
      "is_important": false,
      "labels": ["INBOX", "STARRED"],
      "has_attachments": false,
      "to": [{"name": "", "email": "user@gmail.com"}],
      "cc": [],
      "bcc": [],
      "account_email": "user@gmail.com"
    }
  ]
}
3. Read a full email threadget_email
Prompt: “Show me the full thread for that contract email”
{
  "status": "success",
  "thread_id": "18e2d3c4d5e6f7a8",
  "messages": [
    {
      "message_id": "msg_001",
      "thread_id": "18e2d3c4d5e6f7a8",
      "subject": "Contract Review - Draft",
      "received_at": "2026-03-15T10:00:00Z",
      "from_email": "user@gmail.com",
      "from_name": "You",
      "is_read": true,
      "is_starred": false,
      "is_important": false,
      "snippet": "Please find attached the draft contract for review...",
      "content": "Hi,\n\nPlease find attached the draft contract for review.\n\nBest regards",
      "labels": ["SENT"],
      "html_body": "",
      "attachments": [
        {"filename": "contract_draft_v1.pdf", "mime_type": "application/pdf", "size": 245000, "attachment_id": "att_001"}
      ],
      "to_emails": ["legal@partner.com"],
      "to_names": ["Legal Team"],
      "cc_emails": ["manager@company.com"],
      "cc_names": ["Jane Smith"],
      "bcc_emails": [],
      "bcc_names": []
    },
    {
      "message_id": "msg_002",
      "thread_id": "18e2d3c4d5e6f7a8",
      "subject": "Re: Contract Review - Final Version",
      "received_at": "2026-03-20T09:45:00Z",
      "from_email": "legal@partner.com",
      "from_name": "Legal Team",
      "is_read": false,
      "is_starred": true,
      "is_important": true,
      "snippet": "Final version with all revisions attached. Ready for signatures.",
      "content": "That works. Final version with all revisions incorporated.\n\nReady for signatures whenever you are.",
      "labels": ["INBOX", "STARRED", "IMPORTANT"],
      "html_body": "",
      "attachments": [
        {"filename": "contract_final.pdf", "mime_type": "application/pdf", "size": 260000, "attachment_id": "att_003"}
      ],
      "to_emails": ["user@gmail.com"],
      "to_names": ["You"],
      "cc_emails": ["manager@company.com"],
      "cc_names": ["Jane Smith"],
      "bcc_emails": [],
      "bcc_names": []
    }
  ]
}

Response Limits

Tool responses are automatically managed to stay within AI model context limits.

Responses exceeding 80,000 characters (~20,000 tokens) are automatically truncated to stay within the 25,000 token-per-tool-result limit. When this happens, the item array is trimmed to fit and metadata flags are added:

// Example: list_emails requested page_size=50 but only 12 items fit
{
  "status": "success",
  "count": 500,          // total matching threads in database
  "page": 1,
  "page_size": 50,       // requested page size
  "results": [ ... ],    // 12 items (trimmed to fit 80k char limit)
  "_truncated": true,    // indicates response was trimmed
  "_total_results": 50   // 50 items were on this page before trimming
}

// Example: get_email with a long thread
{
  "status": "success",
  "thread_id": "abc123",
  "messages": [ ... ],       // first N messages that fit
  "_truncated": true,
  "_total_messages": 45      // thread has 45 messages total
}
  • _truncated — present and set to true when the response was trimmed
  • _total_results, _total_messages, or _total_related_emails — how many items existed before trimming
  • Compare the array length to the total to see how many were dropped
  • The AI can request more data by using a smaller page_size, paginating with page=2, or using more specific queries

Error Handling

All tools return structured JSON. Errors include a code and human-readable message.

{
  "status": "error",
  "message": "Human-readable error description.",
  "error_code": "ERROR_CODE"
}
Error CodeMeaningWhat to do
MISSING_API_KEYNo authentication providedConnect via Claude connector or add API key
UNAUTHORIZEDInvalid, expired, or revoked keyGenerate a new key at emailzap.co/mcp-server
BAD_REQUESTInvalid request parametersCheck parameters (e.g. invalid account email)
TIMEOUTSearch took too long (120s limit)Try a more specific search query
CONNECTION_ERRORCould not reach EmailZapCheck internet; service may be temporarily down
SERVER_ERRORUnexpected errorTry again; if persistent, contact support

Security & Privacy

Read-only access

Tools can only read emails. No sending, deleting, or modifying.

API keys are hashed

SHA-256 hashing. Raw key shown only once at creation.

Revocable anytime

Instantly revoke keys from the MCP setup page.

No data stored

MCP server is stateless. Email data lives on the backend only.

HTTPS only

All communication encrypted via TLS.

OAuth 2.0 + PKCE

Claude connector uses secure authorization code flow with PKCE.

Frequently Asked Questions