Inbox Zero MCP Server: Drafts, Calendar, Attachments

Overview

The Inbox Zero MCP Server is the Model Context Protocol (MCP) backend used by the Inbox Zero project to power AI-assisted email workflows. It centralizes mail and calendar context, drafts reply suggestions, extracts and indexes attachments, and exposes those capabilities to clients and chat interfaces (Slack, Telegram, web). The server ties together mailbox connectors (Gmail, Microsoft), an LLM provider (OpenAI by default), and a relational datastore so clients can request context-aware drafts, meeting briefs, and attachment actions without querying the raw mailboxes themselves.

For developers, the MCP server functions as the canonical API and context store for automation agents. It gives you structured access to email threads, conversation metadata, smart rules, and attachment lifecycle management — suitable for building chatops, mobile assistants, or custom inbox automations.

Features

• Draft generation: produce reply drafts in your tone using an LLM with email and calendar context.
• Calendar-aware briefs: generate meeting summaries and pre-meeting context from emails and calendar events.
• Attachment extraction: index attachments, surface relevant files, and support auto-save to cloud drives.
• Cursor / MCP endpoints: expose a machine-friendly API for agents and interactive clients.
• Chat integrations: Slack and Telegram webhook handlers for on-the-go inbox control.
• Tracking and analytics hooks: emit events to PostHog (or similar) for activity monitoring.
• Rules & automation: apply human-readable “cursor rules” to route, archive, block cold email, or unsubscribe in bulk.
• Persistence: relational storage via PostgreSQL + Prisma for reliable context querying.

Architecture (at-a-glance)

Installation / Configuration

Prereqs: Docker (for DB), Node.js (v18+ or v24), pnpm or npm.

1. Clone repo and prepare dev DB (example uses Docker Compose):

git clone https://github.com/elie222/inbox-zero.git
cd inbox-zero
docker compose -f docker-compose.dev.yml up -d

2. Install dependencies and run interactive setup:

pnpm install
# Optional: run repo-level setup script if present
npm run setup

3. Run Prisma migrations and start the MCP server:

cd apps/mcp-server
pnpm prisma migrate dev    # creates schema and local DB tables
pnpm dev                   # or: NODE_ENV=production pnpm start

4. Example environment variables (.env):

DATABASE_URL=postgresql://postgres:password@localhost:5432/inboxzero
OPENAI_API_KEY=sk-...
GMAIL_CLIENT_ID=...
GMAIL_CLIENT_SECRET=...
TELEGRAM_BOT_TOKEN=123456:ABC-DEF
SLACK_SIGNING_SECRET=...
POSTHOG_API_KEY=ph_...
PORT=4000

Notes:

• For production deployments, wire proper OAuth credentials for Gmail/Microsoft connectors and secure your env secrets.
• You can run the MCP server alongside the rest of the monorepo (web app, workers) or as a standalone service that other apps call.

Available Resources

• OpenAPI / MCP spec: the server exposes an OpenAPI-compatible spec (useful for generating clients and for Cursor plugin integration).
• Cursor plugin: the repo includes a Cursor plugin for interactive agents and CLI access; it can call the MCP API skill endpoints.
• Prisma schema and migrations: located in the app directory for database introspection and type generation.
• Webhook endpoints: Slack and Telegram handlers accept signed requests to trigger actions and replies.

Use Cases

• Quick reply from Slack: send a message to the Inbox Zero bot in Slack like “Draft a reply to the latest email from Alice about the Q3 report” — the bot calls the MCP endpoints to fetch thread context and returns a draft.
• Meeting brief on mobile: before a calendar event, request “Summarize pre-meeting context” in Telegram. MCP aggregates recent related emails and returns a one-paragraph brief plus key attachments.
• Auto-save important attachments: create a rule to auto-move PDF attachments from invoices to a cloud drive; MCP extracts attachments and triggers uploader integrations.
• Inbox clean-up: run bulk unsubscriber or bulk archive flows driven by cursor rules stored in the MCP context store.

Best Practices

• Keep LLM prompts and token usage controlled — use the MCP server to pre-compute truncated contexts and embeddings where appropriate.
• Use PostHog events to monitor automation safety (e.g., how many drafts are auto-sent vs. suggested).
• Secure webhook endpoints (Slack, Telegram) and validate signatures to prevent unauthorized actions.

Where to learn more

• Project GitHub: https://github.com/elie222/inbox-zero/tree/main/apps/mcp-server
• Inbox Zero docs (hosting, OAuth, production guides) linked from the repo README.