@inbox-api/mcp

MCP server for Inbox API — give AI agents secure email access through the Model Context Protocol.

Quick Start

npx @inbox-api/mcp

Setup

1. Get an API Token

Sign up at inbox-api.com, connect your email accounts, and create an API token.

2. Configure Your MCP Client

Add to your MCP client configuration (e.g., claude_desktop_config.json):

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

3. Use It

Ask your AI agent to read email, search for messages, send replies, manage drafts, or set up webhooks.

Available Tools (41)

Reading & Search

| Tool | Description | |------|-------------| | list_accounts | List connected email accounts with message and unread counts | | list_messages | List emails with filters (account, folder, read/starred status, date range, attachments, sort) | | get_message | Read a full email message including body content (supports format: text, html, raw) | | get_thread | Get an entire conversation thread with all messages | | list_threads | List email threads with filters (account, unread, date range, pagination) | | search | Full-text BM25 search across all accounts with filters and relevance ranking |

Sending & Composition

| Tool | Description | |------|-------------| | send_email | Compose and send a new email (to/cc/bcc, subject, text or HTML body) | | reply | Reply to an existing message (supports reply-all) | | forward | Forward a message with all attachments to new recipients | | create_draft | Save an email draft for later review or sending | | update_draft | Update an existing email draft | | send_draft | Send a previously saved draft | | delete_draft | Delete a draft | | list_drafts | List drafts with filters (account, date range, pagination) | | get_draft | Get draft details by ID |

Message Actions

| Tool | Description | |------|-------------| | mark_read | Mark a message as read | | mark_unread | Mark a message as unread | | archive | Archive a message (move to archive folder) | | delete_message | Delete a message | | move | Move a message to a different folder |

Batch Operations

| Tool | Description | |------|-------------| | batch_mark_read | Mark multiple messages as read/unread in one request | | batch_archive | Archive multiple messages in one request | | batch_move | Move multiple messages to a folder in one request |

Webhooks

| Tool | Description | |------|-------------| | list_webhooks | List webhook subscriptions (filterable by active status, sortable) | | create_webhook | Register a webhook for email event notifications | | get_webhook | Get webhook details by ID | | update_webhook | Update webhook configuration | | delete_webhook | Delete a webhook subscription | | regenerate_webhook_secret | Regenerate webhook signing secret | | list_webhook_deliveries | List delivery attempts for a webhook | | retry_webhook_delivery | Retry a failed webhook delivery | | purge_webhook_deliveries | Purge old delivery records for a webhook | | list_webhook_templates | List available webhook event templates |

Metadata & Utilities

| Tool | Description | |------|-------------| | list_folders | List all folders for an email account | | list_attachments | List attachments for a message | | get_attachment | Get attachment metadata and download URL | | get_digest | Get a digest of recent emails across accounts | | list_contacts | List frequency-ranked contacts from message headers | | get_account_health | Check IMAP connection health and sync status |

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | INBOX_API_TOKEN | Yes | -- | Your API token (starts with cw_) | | INBOX_API_URL | No | https://api.inbox-api.com | API base URL (for self-hosted instances) |

How It Works

The server uses stdio transport to communicate with MCP clients. It authenticates to the Inbox API using Bearer token authentication and translates tool calls into REST API requests. Responses are formatted as human-readable text optimized for language model consumption.

Prerequisites

• Node.js >= 18
• An Inbox API account with an API token

Development

# Build (requires @inbox-api/client built first)
npm run build

# Watch mode
npm run dev

# Run locally
INBOX_API_TOKEN=cw_xxx npm start

License

MIT