mailbox

This MCP server provides a local integration between mailbox.org and Claude Desktop, enabling Claude to read, search, compose, filter, and manage emails and calendars from your mailbox.org account. It exposes tools for email reading and search, sending and drafting, folder navigation, and management of sieve filters, along with CalDAV calendar access. After starting the server, configure Claude Desktop to connect to the local MCP endpoint so Claude can issue MCP commands like search_emails, get_email, send_email, create_draft, get_calendar_events, and manage sieve scripts. The server includes connection pooling and session-based caching to improve performance during repeated queries and operations.

You can use the available tools in Claude to perform common tasks such as searching emails by text, sender, or date range; retrieving complete email content and threads; sending rich emails with attachments; saving and editing drafts; organizing emails into folders; and managing calendar events with free/busy checks. For calendars, you can retrieve events within a date range, search by title or description, and handle recurring events with multi-calendar aggregation. For email filtering, you can list, create, update, activate/deactivate, delete, and validate Sieve scripts, as well as discover server capabilities for supported extensions.

Prerequisites:

• Node.js 20 or later installed on your system
• Git (for cloning the repository)
• Bun (or your preferred package manager) if the project uses Bun tooling

Installation steps:

1. Clone the repository and install dependencies:

git clone <repository-url>
cd mailbox-mcp-server
bun install

2. Build the project (as per README):

bun run build

3. Create and configure environment variables:

cp env.example .env

Edit .env to include required credentials and optional configuration:

MAILBOX_EMAIL=your-email@mailbox.org
MAILBOX_PASSWORD=your-app-specific-password
MAILBOX_IMAP_HOST=imap.mailbox.org
MAILBOX_IMAP_PORT=993
MAILBOX_IMAP_SECURE=true
MAILBOX_SMTP_HOST=smtp.mailbox.org
MAILBOX_SMTP_PORT=587
MAILBOX_SMTP_SECURE=true
MAILBOX_CALDAV_URL=https://dav.mailbox.org/
DEBUG=false

4. Run or configure the MCP server in Claude Desktop:

# If running directly for development
node /path/to/mailbox-mcp-server/dist/main.js

5. Add the server to Claude Desktop configuration (example):

{
  "mcpServers": {
    "mailbox-mcp-server": {
      "command": "node",
      "args": ["/path/to/mailbox-mcp-server/dist/main.js"]
    }
  }
}

Optional: Ensure that the environment variables are properly loaded in your runtime environment or via a process manager (e.g., systemd, PM2) if starting as a service.

Tips and notes:

• Use an app password for MAILBOX_PASSWORD rather than your main account password for security.
• Ensure IMAP and SMTP settings match mailbox.org defaults unless you have custom endpoints.
• The server supports caching and health monitoring; if you encounter slow responses, check cache TTLs and connection pool settings in your environment.
• For debugging, set DEBUG=true to enable verbose logging during startup.
• If Claude cannot connect, verify that the local MCP endpoint is reachable from your Claude Desktop configuration and that the dist/main.js path matches your built output.
• Sieve filters can be validated before deployment; use check_sieve_script to catch syntax errors before activating filters.