Mailbox.org MCP Server

A Model Context Protocol (MCP) server that integrates mailbox.org email and calendar services with Anthropic's Claude Desktop application. This server enables Claude to access, search, and interact with your personal email and calendar data through a secure, locally-hosted interface.

Features

Email Integration (IMAP & SMTP)

Reading & Search:

• ✅ Search emails by text content, sender, subject, and date range
• ✅ Retrieve complete email content including headers, body, and attachments
• ✅ Email thread management with conversation grouping
• ✅ Folder browsing and navigation (INBOX, Sent, Drafts, etc.)
• ✅ Attachment detection and metadata extraction

Composition & Management:

• ✅ Send emails with rich content (HTML/text) and attachments
• ✅ Draft management - save and edit email drafts
• ✅ Email organization - move emails between folders
• ✅ Flag management - mark as read/unread, important, etc.
• ✅ Email deletion - trash or permanent removal

Performance:

• ✅ Connection pooling for SMTP and IMAP with health monitoring
• ✅ Session-based caching for improved performance

Calendar Integration (CalDAV)

• ✅ Retrieve calendar events within specified date ranges
• ✅ Search calendar events by title, description, location
• ✅ Free/busy time checking for scheduling
• ✅ Multi-calendar support and aggregation
• ✅ Recurring events and exception handling
• ✅ Connection pooling for CalDAV with automatic retry logic
• ✅ Session-based caching for improved performance

Email Filter Management (Sieve/ManageSieve)

• ✅ List and retrieve existing Sieve filter scripts
• ✅ Create and update email filtering rules with Sieve syntax
• ✅ Activate/deactivate filter scripts
• ✅ Delete unwanted filter scripts
• ✅ Syntax validation before deploying filters
• ✅ Server capabilities discovery for supported Sieve extensions

Requirements

• Node.js 20 or later
• A mailbox.org account
• Claude Desktop application

Installation

1. Clone and build the project:

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

2. Copy the example environment file and update it with your credentials:

   cp env.example .env
   

   Note: For security, it's recommended to use an App Password instead of your main account password.

3. Edit the .env file with your mailbox.org credentials:

   # Required settings
   MAILBOX_EMAIL=your-email@mailbox.org
   MAILBOX_PASSWORD=your-app-specific-password
   
   # Optional: IMAP configuration (defaults shown)
   MAILBOX_IMAP_HOST=imap.mailbox.org
   MAILBOX_IMAP_PORT=993
   MAILBOX_IMAP_SECURE=true
   
   # Optional: SMTP configuration (defaults shown)
   MAILBOX_SMTP_HOST=smtp.mailbox.org
   MAILBOX_SMTP_PORT=587
   MAILBOX_SMTP_SECURE=true
   
   # Optional: CalDAV configuration (defaults shown) 
   MAILBOX_CALDAV_URL=https://dav.mailbox.org/
   
   # Optional: Enable debug logging
   DEBUG=false
   

4. Add to Claude Desktop configuration:

   Add this server to your Claude Desktop claude_desktop_config.json:

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

Available Tools

Email Tools

Reading & Search

• search_emails - Search your mailbox by text, sender, date, etc.
• get_email - Retrieve complete email content by UID
• get_email_thread - Get conversation threads by message ID
• get_folders - List all available email folders

Composition & Sending

• send_email - Compose and send emails with attachments
• create_draft - Save email drafts for later editing

Email Management

• move_email - Move emails between folders
• mark_email - Mark emails as read/unread, flag as important
• delete_email - Delete emails (move to trash or permanent)

Calendar Tools

• get_calendar_events - Retrieve events in date range
• search_calendar - Search events by keyword
• get_free_busy - Check availability for scheduling

Sieve Filter Tools

Manage email filtering rules using the Sieve language (RFC 5228) through the ManageSieve protocol.

Script Management

• list_sieve_scripts - List all Sieve filter scripts on the server
• get_sieve_script - Retrieve the content of a specific Sieve script
• create_sieve_filter - Create or update a Sieve filter script
• delete_sieve_script - Delete a Sieve script from the server
• activate_sieve_script - Activate a specific Sieve script (deactivates others)

Script Validation

• check_sieve_script - Validate Sieve script syntax without saving
• get_sieve_capabilities - Get ManageSieve server capabilities and supported extensions

Example Use Cases

Automatic Newsletter Filtering:

require ["fileinto"];

if header :contains "From" [
  "newsletter@example.com",
  "news@company.com"
] {
  fileinto "Newsletter";
  stop;
}

Transaction Email Organization:

require ["fileinto"];

if anyof (
  header :contains "From" ["paypal.de", "stripe.com"],
  header :contains "Subject" ["Order", "Receipt", "Invoice"]
) {
  fileinto "Transactional";
  stop;
}

Ask Claude to manage your filters:

• "Analyze my inbox and suggest email filters"
• "Create a filter to move all GitHub notifications to a Developer folder"
• "Show me all my active Sieve filters"
• "Validate this Sieve script for syntax errors"

Configuration

Environment Variables

Configuration is automatically validated at startup using comprehensive validation rules. The server will fail fast with clear error messages if any configuration is invalid or missing.

Required Configuration

• MAILBOX_EMAIL: Your mailbox.org email address (required)
  • Must be a valid email address format
• MAILBOX_PASSWORD: Your mailbox.org app password (required)
  • Must be a non-empty string

Optional Email Configuration

IMAP (Reading Emails):

• MAILBOX_IMAP_HOST: IMAP server host (default: imap.mailbox.org)
  • Must be a non-empty string
• MAILBOX_IMAP_PORT: IMAP server port (default: 993)
  • Must be a valid port number (1-65535)
• MAILBOX_IMAP_SECURE: Use TLS encryption (default: true)
  • Must be "true" or "false"

SMTP (Sending Emails):

• MAILBOX_SMTP_HOST: SMTP server host (default: smtp.mailbox.org)
  • Must be a non-empty string
• MAILBOX_SMTP_PORT: SMTP server port (default: 465)
  • Must be a valid port number (1-65535)
• MAILBOX_SMTP_SECURE: Use TLS encryption (default: true)
  • Must be "true" or "false"

Optional Calendar Configuration

• MAILBOX_CALDAV_URL: CalDAV server URL (default: https://dav.mailbox.org/)
  • Must be a valid URL format
• MAILBOX_CALENDARS: Comma-separated list of calendars to access

Optional Sieve Configuration

• MAILBOX_SIEVE_HOST: Sieve server host (default: imap.mailbox.org)
  • Must be a non-empty string
• MAILBOX_SIEVE_PORT: Sieve server port (default: 4190)
  • Must be a valid port number (1-65535)
• MAILBOX_SIEVE_SECURE: Use TLS encryption (default: false)
  • Must be "true" or "false"

Optional Cache Configuration

All cache TTL values must be non-negative numbers (in milliseconds):

• CACHE_EMAIL_SEARCH_TTL: Email search cache TTL in ms (default: 300000)
• CACHE_EMAIL_MESSAGE_TTL: Email message cache TTL in ms (default: 600000)
• CACHE_EMAIL_THREAD_TTL: Email thread cache TTL in ms (default: 300000)
• CACHE_CALENDAR_EVENTS_TTL: Calendar events cache TTL in ms (default: 900000)
• CACHE_CALENDAR_FREEBUSY_TTL: Calendar free/busy cache TTL in ms (default: 300000)
• CACHE_MAX_SIZE: Maximum cache entries (default: 1000)
  • Must be a positive integer
• CACHE_CLEANUP_INTERVAL: Cache cleanup frequency in ms (default: 300000)
  • Must be at least 1000ms

Optional Connection Pool Configuration

Note: mailbox.org limits concurrent IMAP connections per account. Using more than 2-3 connections may cause connection issues.

• POOL_MAX_CONNECTIONS: Maximum total connections (default: 2 - safe for mailbox.org)
  • Must be between 1 and 100 connections
• POOL_TIMEOUT_MS: Connection acquire timeout (default: 15000)
  • Must be at least 1000ms
• POOL_IDLE_TIMEOUT_MS: Idle connection timeout (default: 30000)
  • Must be at least 1000ms
• POOL_HEALTH_CHECK_MS: Health check frequency (default: 6000)
  • Must be at least 1000ms

Optional Debug Configuration

• DEBUG: Enable debug logging (default: false)
  • Must be "true" or "false"

Security Notes

• Use app-specific passwords instead of your main password for better security
• All credentials are passed via environment variables (no persistent storage)
• Consider using a .env file for local development (add it to .gitignore)

Security Features

• ✅ TLS encryption for all IMAP, SMTP, CalDAV, and CardDAV connections
• ✅ Connection pooling with health monitoring - automatic detection and recovery from failed connections
• ✅ Local-only processing - no data sent to third parties
• ✅ Environment-based credentials - no persistent storage of passwords
• ✅ App-specific password support for enhanced security
• ✅ Session-only caching - all data cleared on restart
• ✅ Privacy-first architecture - your data stays on your machine

Architecture

Connection Pooling

The server implements robust connection pooling for optimal performance and reliability:

SMTP Connection Pool

• Verification Timing: Connections are verified based on configurable intervals to avoid unnecessary overhead
• Failure Tracking: Monitors connection health and automatically destroys connections after repeated failures
• Retry Logic: Automatic retry with exponential backoff for failed connection attempts
• Metrics: Real-time monitoring of pool status, verification failures, and connection distribution

IMAP Connection Pool

• Folder-Aware Pooling: Connections remember selected folders to minimize folder switching overhead
• Health Monitoring: Periodic validation using IMAP NOOP commands
• Connection Reuse: Intelligent reuse of connections for the same folder operations
• State Management: Automatic cleanup of folder state for unhealthy connections

Base Pool Features

• Sensible Defaults: Production-ready configuration that works out of the box
• Simple Tuning: Only 4 configuration variables for essential performance tuning
• Health Checks: Background monitoring and cleanup of idle/unhealthy connections
• Graceful Shutdown: Proper cleanup of all connections on server termination
• Error Recovery: Automatic recreation of failed connections with hardcoded retry logic

Performance Benefits

• Reduced Latency: Connection reuse eliminates costly connection establishment overhead
• Better Throughput: Multiple concurrent operations through connection pooling
• Resource Efficiency: Automatic scaling based on demand within configured limits
• Reliability: Health monitoring ensures only working connections are used

Development

Setup

1. Clone the repository:

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

2. Install dependencies:

   bun install
   

   Note: This project uses bun as the package manager. Make sure you have bun installed (version 1.0 or later recommended).

3. Create environment configuration:

   cp .env.example .env
   # Edit .env with your mailbox.org credentials
   

Debugging with Inspector

The MCP Inspector is a powerful tool for debugging and monitoring your MCP server. It provides real-time insights into errors, request/response cycles, and server state.

Enabling the Inspector

1. Start the server with inspector enabled:

   MCP_INSPECTOR=true bun start
   

2. Access the web UI at http://localhost:3000/inspector (port may vary based on your configuration)

Key Features

• Real-time Error Monitoring

  • View errors as they occur
  • See detailed stack traces and context
  • Filter errors by type and severity

• Request/Response Inspection

  • Monitor all MCP protocol messages
  • Inspect request/response payloads
  • View timing information

• Tool Validation

  • Validate tool definitions against MCP specifications
  • Get warnings about potential issues

Common Debugging Workflow

1. Reproduce the Issue

   • Perform the action that causes the error
   • Note any error messages or unexpected behavior

2. Inspect the Error

   • Look for red indicators in the Inspector UI
   • Expand error entries for detailed information
   • Check the network tab for failed requests

3. View Context

   • Examine the server state at the time of the error
   • Check the request payload and headers
   • Look at previous successful requests for comparison

Enabling Verbose Logging

For more detailed debugging information, enable debug mode:

MCP_DEBUG=true MCP_INSPECTOR=true bun start

Best Practices

• Keep the Inspector open during development
• Use the search/filter functionality to find specific errors
• Take advantage of the "Resend" feature to retry failed requests
• Use the "Copy as cURL" feature to share reproducible test cases

Available Scripts

• bun dev - Start development server with hot reloading
• bun run build - Build for production
• bun start - Start production server
• bun run test - Run test suite
• bun run test:unit - Run unit tests only
• bun run test:integration - Run integration tests only
• bun format - Format code with Biome
• bun lint - Lint code with Biome
• bun check - Run both linting and formatting

Testing

The project includes comprehensive test coverage:

• Unit tests: Service layer logic testing
• Integration tests: Real mailbox.org API testing
• Mock services: IMAP/CalDAV/CardDAV protocol testing

# Run all tests
bun run test

# Run with coverage
bun run test:coverage

# Test specific service
bun run test ImapService

Dependencies

This project relies on the following key dependencies:

• Runtime Dependencies

  • @modelcontextprotocol/sdk - MCP server implementation
  • imapflow - IMAP client for email access
  • tsdav - CalDAV client for calendar access
  • ical.js - iCalendar parsing library
  • mailparser - Email message parsing
  • dayjs - Date manipulation library

• Development Dependencies

  • typescript - TypeScript compiler
  • vitest - Testing framework
  • biome - Code formatting and linting
  • @types/* - TypeScript type definitions

Troubleshooting

Common Issues

1. Connection Issues

   • Verify your mailbox.org credentials in .env
   • Check if your account has IMAP and CalDAV access enabled
   • Ensure your network allows outbound connections to mailbox.org servers

2. Authentication Failures

   • Use an App Password instead of your main password
   • Make sure 2FA is properly configured if enabled

3. Missing Dependencies

   # If you encounter module not found errors:
   bun install
   

4. Debugging

   • Enable debug mode for more detailed logs:

     DEBUG=true bun start
     

   • Check the Debugging with Inspector section for advanced troubleshooting

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure to update tests as appropriate and follow the project's code style.

License

MIT License - see LICENSE file for details