mcp-inbox

mcp-inbox

AI Inbox Manager — MCP Server with 15 tools for unified inbox management + email send/reply/poll via IMAP + SMTP.

Give your AI assistant full email powers: read, search, triage, send, reply, and manage a multi-channel inbox with lead scoring and priority detection.

Features

• 15 MCP Tools — 10 read, 2 write, 3 email (send/reply/poll)
• Multi-Channel Inbox — email, web forms, Telegram, custom channels
• Multi-Mailbox — 4 configurable mailboxes (hello, support, sales, info)
• IMAP Polling — Fetch unseen emails (read-only, non-destructive)
• SMTP Sending — Send emails with DKIM support, file attachments up to 25 MB
• Thread Tracking — Email threading with In-Reply-To/References headers
• AI Triage — Lead scoring, urgency detection, intent classification
• Priority Detection — High-urgency items and high lead-score filtering
• Dual Transport — stdio (default) + Streamable HTTP mode
• PostgreSQL — Prisma ORM with full schema included

Quick Start

1. Install

npm install

2. Set up the database

# Set DATABASE_URL in .env or environment
export DATABASE_URL="postgresql://user:pass@localhost:5432/inbox"

# Push schema to database
npx prisma db push

3. Configure email (optional — inbox tools work without email)

# .env
EMAIL_DOMAIN=yourdomain.com
EMAIL_ORG_NAME="Your Company"

# IMAP (for polling incoming emails)
IMAP_HOST=imap.yourdomain.com
IMAP_PORT=993
IMAP_PASS=your-imap-password

# SMTP (for sending emails)
SMTP_HOST=smtp.yourdomain.com
SMTP_PORT=587
SMTP_USER=your-smtp-user
SMTP_PASS=your-smtp-password

4. Build and run

npm run build
npm start          # stdio mode (for Claude Desktop, Cursor, etc.)
npm start -- --http  # HTTP mode on port 4008

5. Connect to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "inbox": {
      "command": "node",
      "args": ["/path/to/mcp-inbox/dist/server.js"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/inbox",
        "EMAIL_DOMAIN": "yourdomain.com",
        "EMAIL_ORG_NAME": "Your Company",
        "IMAP_HOST": "imap.yourdomain.com",
        "IMAP_PASS": "your-password",
        "SMTP_HOST": "smtp.yourdomain.com",
        "SMTP_PORT": "587",
        "SMTP_USER": "your-user",
        "SMTP_PASS": "your-password"
      }
    }
  }
}

Tools Reference

Reading (10 tools)

Tool	Description	Parameters
inbox_list	List/filter inbox items	channel?, status?, search?, fromDate?, toDate?, limit?, offset?
inbox_get	Get single item with body + triage	id
inbox_search	Full-text search across all fields	query, limit?
inbox_stats	Overview: total, by status/channel, high-priority count	—
inbox_threads	Email threads with message counts	limit?
inbox_get_thread	Thread details with all messages	threadKey
inbox_high_priority	Items needing immediate attention	—
inbox_notes	Triage notes: TLDR, intent, urgency, score	inboxItemId
inbox_recent	Last N items across all channels	limit?
inbox_channel_summary	Per-channel breakdown	—

Writing (2 tools)

Tool	Description	Parameters
inbox_update_status	Change status: new -> processed -> notified -> archived	id, status
inbox_archive_old	Auto-archive old processed items	olderThanDays? (default: 30)

Email (3 tools)

Tool	Description	Parameters
email_send	Send email via SMTP with optional attachments	to, subject, text, html?, replyTo?, mailbox?, attachments?
email_reply	Reply to existing inbox thread (auto-threading)	inboxItemId, text, html?
email_poll	Poll IMAP for unseen emails (read-only)	maxCount?, mailbox?

Resources (2)

Resource	URI	Description
Inbox Stats	inbox://stats	Current inbox statistics
High Priority	inbox://high-priority	Items needing attention

Database Schema

Three Prisma models included:

• InboxItem — Messages from any channel (email, web, Telegram, form)
• InboxNote — AI triage notes with TLDR, intent, urgency, lead score
• EmailThread — Thread tracking with message counts and auto-reply status

Enums: Channel (web/telegram/email/form), InboxStatus (new/processed/notified/archived), Urgency (low/mid/high)

Mailboxes

4 configurable mailboxes, each with its own IMAP user and SMTP sender:

Mailbox	Email	Sender Name
hello (default)	hello@{domain}	{org}
support	support@{domain}	{org} Support
sales	sales@{domain}	{org} Sales
info	info@{domain}	{org} Info

Set EMAIL_DOMAIN and EMAIL_ORG_NAME environment variables to configure.

Architecture

src/
  server.ts          — MCP server with 15 tool registrations
  core/
    db.ts            — Prisma database queries (inbox, notes, threads, stats)
    email.ts         — IMAP polling + SMTP sending + thread replies
  lib/
    dual-transport.ts — stdio + Streamable HTTP transport
    logger.ts        — Structured stderr logging
prisma/
  schema.prisma      — Database schema (3 models, 3 enums)

Environment Variables

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string
EMAIL_DOMAIN	No	Email domain (default: example.com)
EMAIL_ORG_NAME	No	Organization name for sender (default: My Organization)
IMAP_HOST	No*	IMAP server hostname
IMAP_PORT	No	IMAP port (default: 993)
IMAP_PASS	No*	IMAP password
IMAP_TLS	No	Enable TLS (default: true)
SMTP_HOST	No*	SMTP server hostname
SMTP_PORT	No	SMTP port (default: 587)
SMTP_USER	No*	SMTP username
SMTP_PASS	No*	SMTP password
MCP_HTTP	No	Set to 1 to enable HTTP transport
MCP_PORT	No	HTTP port override (default: 4008)
MCP_HOST	No	HTTP bind address (default: 127.0.0.1)
MCP_DEBUG	No	Set to 1 for debug logging

* Required for email tools (email_send, email_reply, email_poll). Inbox tools work without email configuration.

Docker

npm run build
docker build -t mcp-inbox .
docker run -p 4008:4008 \
  -e DATABASE_URL="postgresql://..." \
  -e MCP_HTTP=1 \
  -e EMAIL_DOMAIN=yourdomain.com \
  mcp-inbox

Tested SMTP Providers

• Brevo (smtp-relay.brevo.com)
• SendGrid (smtp.sendgrid.net)
• Postmark (smtp.postmarkapp.com)
• AWS SES
• Any standard SMTP relay

License

MIT