📧 Mailcow MCP Server
Model Context Protocol (MCP) server for complete Mailcow email server management
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
- CLAUDE.md - Essential context for Claude Code sessions
- Team Structure - Parallel development workflow
🔧 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
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Add tests for your changes
- Ensure all tests pass:
npm run test:all - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - 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
- Documentation: docs/README.md
- Issues: GitHub Issues
- Discussions: GitHub Discussions
🙏 Acknowledgments
- Model Context Protocol - The protocol that makes this possible
- Mailcow - The excellent email server platform
- TypeScript - For robust type safety and excellent tooling
Bringing AI and email servers together, one tool at a time.