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.

主な機能

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

ユースケース

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.