Mailcow

โ€ข
9
โ€ข

Enables AI models to gain full control over Mailcow email servers via the Model Context Protocol.

The Mailcow MCP Server provides a powerful bridge between AI models and your Mailcow email server, leveraging the Model Context Protocol. This comprehensive TypeScript implementation offers a secure, unified API to manage all aspects of your email infrastructure. From handling domains and mailboxes to orchestrating email sending, queue management, and synchronization jobs, it empowers AI to automate complex email operations with high performance and robust security.

Key Features

01Complete Email Management with 20 MCP tools for full Mailcow control
02Comprehensive Logging for full audit trails and monitoring capabilities
03High Performance built with TypeScript for speed and reliability
040 GitHub stars
05Enterprise Security with API key authentication and granular permissions
06Production Ready, deployed and tested in live environments

Use Cases

01Programmatically managing email domains, mailboxes, and user quotas through an API.
02Automating email sending, delivery status checks, and template usage for AI-driven communications.
03Monitoring Mailcow server health, configurations, and analyzing various system logs via AI integration.

๐Ÿ“ง Mailcow MCP Server

Model Context Protocol (MCP) server for complete Mailcow email server management

TypeScript MCP Node.js License

A comprehensive TypeScript implementation that provides AI models with full control over Mailcow email servers through the Model Context Protocol. Manage domains, mailboxes, queues, sync jobs, and send emails - all with a single, secure API.

โœจ Features

๐ŸŽฏ Complete Email Management - 20 MCP tools for full Mailcow control
๐Ÿ”’ Enterprise Security - API key authentication with granular permissions
โšก High Performance - Built with TypeScript for speed and reliability
๐Ÿ“Š Comprehensive Logging - Full audit trail and monitoring capabilities
๐Ÿงช Well Tested - Extensive test suite with >85% coverage on core modules
๐Ÿš€ Production Ready - Used in production environments

๐Ÿš€ Quick Start

# 1. Install dependencies
npm install

# 2. Configure environment  
cp .env.example .env
# Edit .env with your Mailcow server details

# 3. Start the server
npm run build && npm start

๐ŸŽ‰ That's it! Your MCP server is now running with 20 tools ready for AI integration.

๐Ÿ‘‰ Detailed setup: Quick Start Guide

๐Ÿ› ๏ธ Available Tools

Email Management (18 tools)

  • Domains (5): List, create, update, delete, get details
  • Mailboxes (5): List, create, update, delete, get details
  • Email Sending (3): Send emails, check delivery status, get templates
  • Queue Management (6): List, flush, delete, hold, release queue items
  • Sync Jobs (7): Manage email migration and synchronization
  • Log Analysis (4): System, error, performance, and access logs

System Tools (3 tools)

  • Health Check: Server status and metrics
  • Configuration: Current settings (sanitized)
  • API Test: Validate Mailcow connectivity

๐Ÿ“Š Current Status

๐ŸŸข MVP Complete - Full email server management capability
๐ŸŸข Production Ready - Deployed and tested in live environments
๐ŸŸข Well Documented - Comprehensive guides and API reference

Component Status Coverage Tools
Domain Management โœ… Complete 85% 5 tools
Mailbox Management โœ… Complete 87% 5 tools
Email System โœ… Complete MVP 3 tools
Queue Management โœ… Complete New 6 tools
Sync Jobs โœ… Complete New 7 tools
Log Management โœ… Complete New 4 tools
System Tools โœ… Complete 100% 3 tools

๐Ÿ—๏ธ Architecture

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚   AI Models     โ”‚    โ”‚   MCP Client    โ”‚    โ”‚   Your App      โ”‚
โ”‚   (Claude, etc) โ”‚โ—„โ”€โ”€โ–บโ”‚   (Claude CLI)  โ”‚โ—„โ”€โ”€โ–บโ”‚   Integration   โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€๏ฟฝ๏ฟฝ๏ฟฝโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                                โ”‚
                                โ–ผ
                       โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
                       โ”‚  MCP Protocol   โ”‚
                       โ”‚   (JSON-RPC)    โ”‚
                       โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                                โ”‚
                                โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                    Mailcow MCP Server                           โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚ Tool Registry โ”‚ โ”‚ Auth Manager  โ”‚ โ”‚   20 MCP Tools        โ”‚  โ”‚
โ”‚  โ”‚ & Validation  โ”‚ โ”‚ & Security    โ”‚ โ”‚ โ€ข Domain Management   โ”‚  โ”‚
โ”‚  โ”‚               โ”‚ โ”‚               โ”‚ โ”‚ โ€ข Mailbox Management  โ”‚  โ”‚
โ”‚  โ”‚               โ”‚ โ”‚               โ”‚ โ”‚ โ€ข Email & Queues      โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€๏ฟฝ๏ฟฝ๏ฟฝโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”‚                                โ”‚                                โ”‚
โ”‚                                โ–ผ                                โ”‚  
โ”‚                    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”                    โ”‚
โ”‚                    โ”‚     API Client        โ”‚                    โ”‚
โ”‚                    โ”‚   (HTTP + Auth)       โ”‚                    โ”‚
โ”‚                    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜                    โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                                โ”‚
                                โ–ผ
                       โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
                       โ”‚  Mailcow Server โ”‚
                       โ”‚   REST API      โ”‚
                       โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

๐Ÿ“š Documentation

Document Purpose
Quick Start Get running in 5 minutes
Architecture System design and components
API Reference Complete tool documentation
Configuration Environment setup guide
Testing Guide Testing framework and practices

Developer Resources

๐Ÿ”ง Development

# Development mode with auto-reload
npm run dev

# Run tests
npm test

# View test coverage
npm run test:coverage

# Lint and format
npm run lint
npm run format

# Build for production
npm run build

๐ŸŒŸ Example Usage

Send an Email

// Send welcome email with template
const result = await mcp.call('send_email', {
  from: 'admin@company.com',
  to: ['user@company.com'],
  subject: 'Welcome to our service!',
  body: 'Your account is ready to use.',
  body_type: 'plain'
});

// Check delivery status  
await mcp.call('check_email_status', { 
  queue_id: result.email_details.queue_id 
});

Manage Domains

// List all active domains
const domains = await mcp.call('list_domains', { 
  active_only: true 
});

// Create new domain
await mcp.call('create_domain', {
  domain: 'newclient.com', 
  description: 'New client domain',
  quota: 5368709120  // 5GB
});

Monitor System

// Check server health
const health = await mcp.call('health_check');

// Get recent error logs
const errors = await mcp.call('get_error_logs', {
  limit: 50,
  start_time: '2023-12-01T00:00:00.000Z'
});

๐Ÿ”’ Security

  • API Key Authentication with Mailcow integration
  • Granular Permissions system (read/write/delete by resource)
  • Input Validation with JSON Schema enforcement
  • Audit Logging for all operations
  • HTTPS Enforcement and SSL certificate validation
  • Rate Limiting to prevent abuse

๐Ÿค Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Add tests for your changes
  4. Ensure all tests pass: npm run test:all
  5. Commit your changes: git commit -m 'Add amazing feature'
  6. Push to the branch: git push origin feature/amazing-feature
  7. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

๐Ÿ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

๐Ÿ†˜ Support

๐Ÿ™ Acknowledgments


Made with โค๏ธ for the AI and email community
Bringing AI and email servers together, one tool at a time.