📧 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: '[email protected]',
  to: ['[email protected]'],
  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

• 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