Model Context Protocol

MCP Server

Give AI agents secure email access through the Model Context Protocol. 33 built-in tools for reading, sending, searching, and managing email — no custom integration code required.

npm

Tools Overview

Reading & Search (7)

list_accounts — List connected accounts
list_messages — List and filter emails
get_message — Read full email content
get_thread — Get conversation thread
list_threads — List email threads
search — Full-text search

Sending & Composition (4)

send_email — Send a new email
reply — Reply to a message
forward — Forward a message
create_draft — Save a draft

Draft Management (5)

update_draft — Update a draft
send_draft — Send a saved draft
delete_draft — Delete a draft
list_drafts — List drafts
get_draft — Get draft details

Message Actions (5)

mark_read — Mark as read
mark_unread — Mark as unread
archive — Archive message
delete_message — Delete message
move — Move to folder

Batch Operations (3)

batch_mark_read — Batch read/unread
batch_archive — Batch archive
batch_move — Batch move

Webhooks (4)

list_webhooks — List subscriptions
get_webhook — Get details
list_webhook_deliveries — Delivery history
retry_webhook_delivery — Retry delivery

Metadata & Utilities (6)

list_folders — List account folders
list_attachments — List attachments
get_attachment — Get attachment info
get_digest — Email digest
list_contacts — Frequent contacts
get_account_health — Account health

Installation

                  Install globally from npm:

npm install -g @inbox-api/mcp

Or use directly with npx (no install needed):

npx @inbox-api/mcp

Configuration

                  The MCP server requires an API token and communicates over stdio.

Environment variables:
  INBOX_API_TOKEN   API token with cw_ prefix (required)
  INBOX_API_URL     API base URL (default: https://api.inbox-api.com)

Claude Desktop

                  Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "inbox-api": {
      "command": "npx",
      "args": ["-y", "@inbox-api/mcp"],
      "env": {
        "INBOX_API_TOKEN": "cw_your_token_here"
      }
    }
  }
}

Config file locations:
  macOS   ~/Library/Application Support/Claude/claude_desktop_config.json
  Windows %APPDATA%/Claude/claude_desktop_config.json
  Linux   ~/.config/Claude/claude_desktop_config.json

Claude Code

                  Add to your project's .mcp.json or global settings:

{
  "mcpServers": {
    "inbox-api": {
      "command": "npx",
      "args": ["-y", "@inbox-api/mcp"],
      "env": {
        "INBOX_API_TOKEN": "cw_your_token_here"
      }
    }
  }
}

Cursor

                  Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "inbox-api": {
      "command": "npx",
      "args": ["-y", "@inbox-api/mcp"],
      "env": {
        "INBOX_API_TOKEN": "cw_your_token_here"
      }
    }
  }
}

Windsurf

                  Add to your Windsurf MCP configuration (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "inbox-api": {
      "command": "npx",
      "args": ["-y", "@inbox-api/mcp"],
      "env": {
        "INBOX_API_TOKEN": "cw_your_token_here"
      }
    }
  }
}

list_accounts

                  List all connected email accounts with message and unread counts.

Parameters: None

Example prompt:
  "List my email accounts"

Response:
  Connected accounts:
  - me@gmail.com (Gmail) — 1,247 messages, 23 unread
  - work@company.com (IMAP) — 3,891 messages, 7 unread

list_messages

                  List emails with filtering, sorting, and pagination.

Parameters:
  accountId       string, optional   Filter by account ID
  folderId        string, optional   Filter by folder ID
  isRead          boolean, optional  Filter by read status
  isStarred       boolean, optional  Filter by starred status
  hasAttachments  boolean, optional  Filter by attachments
  startDate       string, optional   Start date (ISO 8601)
  endDate         string, optional   End date (ISO 8601)
  sort            string, optional   date (default), date_asc, subject, from
  page            number, default: 1  Page number
  pageSize        number, default: 10 Results per page (max 100)

Example prompts:
  "Show my unread emails"
  "List emails from the last 7 days"
  "Show starred messages in my work account"

Response:
  Messages (page 1 of 5, 47 total):
  * 2026-03-25 14:30  alice@example.com — Q3 Report [attachments]
    2026-03-25 10:15  bob@company.com — Re: Meeting notes
  * 2026-03-24 18:00  noreply@github.com — PR #42 merged
    (* = unread)

get_message

                  Read a full email including headers, body content, and metadata.

Parameters:
  messageId    string, required   ID of the message to read
  format       string, optional   Body format: "raw" or "llm"

Use format: "llm" to get a cleaner body optimized for AI consumption:
  — HTML converted to markdown
  — Email signatures stripped (RFC 3676 and heuristic patterns)
  — Reply chain quotes removed (blockquotes, Gmail quotes, > lines)
  — Whitespace normalized

Example prompts:
  "Read message abc123"
  "Show me the full email from Alice about the Q3 report"

Response:
  From: Alice <alice@example.com>
  To: me@company.com
  Date: 2026-03-25 14:30
  Subject: Q3 Report
  Status: Unread | Has Attachments
  ──────────────────────────
  Hi, please find the Q3 report attached.
  Best, Alice

get_thread

                  Get an entire conversation thread with all messages.

Parameters:
  threadId     string, required   ID of the thread

Example prompts:
  "Show me the full thread about the Q3 report"
  "Get conversation thread xyz789"

Response:
  Thread: Q3 Report (3 messages, 1 unread)

  [1/3] 2026-03-24 10:00 — alice@example.com
  Hi, I'll send the Q3 report by end of day.

  [2/3] 2026-03-25 09:15 — me@company.com
  Thanks Alice, no rush.

  [3/3] 2026-03-25 14:30 — alice@example.com
  Here's the report, attached as PDF.

search

                  Full-text BM25 search across all accounts with optional filters.

Parameters:
  query           string, required   Search query
  accountId       string, optional   Limit to specific account
  isRead          boolean, optional  Filter by read status
  isStarred       boolean, optional  Filter by starred status
  hasAttachments  boolean, optional  Filter by attachments
  startDate       string, optional   Start date (ISO 8601)
  endDate         string, optional   End date (ISO 8601)
  sort            string, optional   relevance (default), date, date_asc, subject, from
  page            number, default: 1  Page number
  pageSize        number, default: 10 Results per page (max 100)

Example prompts:
  "Search for emails about invoices"
  "Find messages from alice@example.com about the Q3 report"
  "Search my work account for 'project deadline'"

send_email

                  Compose and send a new email.

Parameters:
  accountId    string, required   Account to send from
  to           array, required    Recipients [{email, name?}]
  subject      string, required   Email subject
  textBody     string, optional   Plain text body
  htmlBody     string, optional   HTML body
  cc           array, optional    CC recipients [{email, name?}]
  bcc          array, optional    BCC recipients [{email, name?}]

Example prompts:
  "Send an email to bob@example.com saying the meeting is moved to 3pm"
  "Email alice@example.com with subject 'Q3 Report' and CC carol@example.com"

Response:
  Email sent successfully.
  Message ID: msg_abc123

reply

                  Reply to an existing email message.

Parameters:
  messageId    string, required   ID of the message to reply to
  textBody     string, optional   Plain text reply body
  htmlBody     string, optional   HTML reply body
  replyAll     boolean, default: false  Reply to all recipients

Example prompts:
  "Reply to the last email from Alice saying 'Thanks, looks great!'"
  "Reply all to message xyz with 'Noted, thanks everyone.'"

Response:
  Reply sent successfully.
  Message ID: msg_def456

forward

                  Forward a message to new recipients with all attachments preserved.

Parameters:
  messageId       string, required   ID of the message to forward
  to              array, required    Recipients [{email, name?}]
  cc              array, optional    CC recipients [{email, name?}]
  bcc             array, optional    BCC recipients [{email, name?}]
  additionalText  string, optional   Text to prepend to the forwarded message

Example prompts:
  "Forward this email to bob@example.com"
  "Forward the invoice email to the finance team with a note saying 'Please review'"

Response:
  Message forwarded successfully.
  Message ID: msg_ghi789

create_draft

                  Save an email draft for later review or sending.

Parameters:
  accountId    string, required   Account for the draft
  to           array, optional    Recipients [{email, name?}]
  cc           array, optional    CC recipients [{email, name?}]
  subject      string, optional   Email subject
  textBody     string, optional   Plain text body
  htmlBody     string, optional   HTML body

Example prompts:
  "Draft an email to the team about the upcoming sprint"
  "Save a draft reply to alice@example.com, I'll finish it later"

Response:
  Draft saved successfully.
  Draft ID: draft_abc123

list_threads

                  List email threads with optional filters and pagination.

Parameters:
  accountId       string, optional   Filter by account ID
  unreadOnly      boolean, optional  Only unread threads
  startDate       string, optional   Start date (ISO 8601)
  endDate         string, optional   End date (ISO 8601)
  page            number, default: 1  Page number
  pageSize        number, default: 10 Results per page (max 100)

Example prompts:
  "Show my recent email threads"
  "List unread threads from the last week"

update_draft

                  Update an existing email draft.

Parameters:
  draftId      string, required   ID of the draft to update
  to           array, optional    Recipients [{email, name?}]
  cc           array, optional    CC recipients [{email, name?}]
  subject      string, optional   Email subject
  textBody     string, optional   Plain text body
  htmlBody     string, optional   HTML body

Example prompts:
  "Update my draft to add Bob to CC"
  "Change the subject of draft xyz to 'Updated Report'"

send_draft

                  Send a previously saved draft.

Parameters:
  draftId      string, required   ID of the draft to send

Example prompts:
  "Send the draft I saved earlier"
  "Send draft abc123"

Response:
  Draft sent successfully.
  Message ID: msg_abc123

delete_draft

                  Delete an email draft.

Parameters:
  draftId      string, required   ID of the draft to delete

Example prompts:
  "Delete draft abc123"
  "Remove the draft about the sprint update"

list_drafts

                  List email drafts with optional filters.

Parameters:
  accountId    string, optional   Filter by account ID
  page         number, default: 1  Page number
  pageSize     number, default: 10 Results per page

Example prompts:
  "Show my drafts"
  "List drafts in my work account"

get_draft

                  Get draft details by ID.

Parameters:
  draftId      string, required   ID of the draft

Example prompts:
  "Show me draft abc123"
  "What's in my draft about the quarterly review?"

mark_read

                  Mark an email message as read.

Parameters:
  messageId    string, required   ID of the message

Example prompts:
  "Mark this message as read"
  "Mark the email from Alice as read"

mark_unread

                  Mark an email message as unread.

Parameters:
  messageId    string, required   ID of the message

Example prompts:
  "Mark this message as unread"
  "I want to come back to this email later, mark it unread"

delete_message

                  Delete an email message.

Parameters:
  messageId    string, required   ID of the message to delete

Example prompts:
  "Delete message abc123"
  "Delete the spam email"

move

                  Move a message to a different folder.

Parameters:
  messageId    string, required   ID of the message to move
  folderId     string, required   Target folder ID

Example prompts:
  "Move this email to my Work folder"
  "Move the invoice to the Finance folder"

batch_mark_read

                  Batch mark multiple messages as read or unread.

Parameters:
  messageIds   array, required    IDs of messages to update
  isRead       boolean, required  Set read (true) or unread (false)

Example prompts:
  "Mark all emails from today as read"
  "Mark these 5 messages as unread"

batch_archive

                  Batch archive multiple messages at once.

Parameters:
  messageIds   array, required    IDs of messages to archive

Example prompts:
  "Archive all read messages from last week"
  "Archive these newsletters"

batch_move

                  Batch move multiple messages to a folder.

Parameters:
  messageIds   array, required    IDs of messages to move
  folderId     string, required   Target folder ID

Example prompts:
  "Move all invoices to the Finance folder"
  "Move these messages to my Archive"

list_webhooks

                  List webhook subscriptions with optional filtering and sorting.

Parameters:
  isActive     boolean, optional  Filter by active status
  sort         string, optional   Sort: date, date_asc, url
  page         number, default: 1  Page number
  pageSize     number, default: 10 Results per page

Example prompts:
  "List my webhooks"
  "Show my webhook subscriptions"

Response:
  Webhooks (2):

  Active: https://my-app.com/webhooks/inbox
    Events: message.received, message.sent
    Payload: Standard
    ID: wh_abc123

get_webhook

                  Get webhook details by ID.

Parameters:
  webhookId    string, required   ID of the webhook

Example prompts:
  "Show details for webhook wh_abc123"
  "What events is my webhook subscribed to?"

list_webhook_deliveries

                  List delivery attempts for a webhook.

Parameters:
  webhookId    string, required   ID of the webhook
  page         number, default: 1  Page number
  pageSize     number, default: 10 Results per page

Example prompts:
  "Show delivery history for my webhook"
  "List recent webhook deliveries"

retry_webhook_delivery

                  Retry a failed webhook delivery.

Parameters:
  webhookId    string, required   ID of the webhook
  deliveryId   string, required   ID of the failed delivery

Example prompts:
  "Retry the failed delivery for webhook wh_abc123"
  "Resend the webhook event that failed"

list_folders

                  List all folders for an email account.

Parameters:
  accountId    string, required   Email account ID

Example prompts:
  "List folders in my Gmail account"
  "Show me the folder structure for my work email"

list_attachments

                  List all attachments on a message.

Parameters:
  messageId    string, required   ID of the message

Example prompts:
  "What attachments does this email have?"
  "List attachments on the Q3 report email"

get_attachment

                  Get attachment metadata and download URL.

Parameters:
  messageId      string, required   ID of the message
  attachmentId   string, required   ID of the attachment

Example prompts:
  "Get the download link for the PDF attachment"
  "Show details for attachment xyz"

get_digest

                  Get an email digest summary across all accounts.

Parameters: None

Example prompts:
  "Give me my email digest"
  "Summarize my recent emails across all accounts"

Response:
  Email Digest:
  me@gmail.com — 5 new, 2 unread
  work@company.com — 12 new, 8 unread

list_contacts

                  List contacts ranked by email frequency.

Parameters:
  accountId    string, optional   Filter by account ID

Example prompts:
  "Who do I email the most?"
  "List my most frequent contacts"

get_account_health

                  Check the IMAP connection health status for an email account.

Parameters:
  accountId    string, required   Email account ID

Example prompts:
  "Is my Gmail account syncing properly?"
  "Check the health of my work email connection"

get_webhook_delivery

                  Get details of a single webhook delivery.

Parameters:
  webhookId    string, required   ID of the webhook
  deliveryId   string, required   ID of the delivery

Example prompts:
  "Show me delivery del_xyz for webhook wh_abc123"
  "Get the details of that failed webhook delivery"

Security

Scoped tokens — API tokens can be restricted to specific email accounts and permission scopes (read, send, drafts, manage).

Zero credential exposure — The LLM never sees email passwords or OAuth tokens. Only scoped API tokens are passed.

Audit trail — All actions through the MCP server are logged with full audit trail in your workspace.

All Documentation

Node.js CLI .NET CLI