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.
๐ฏ 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
# 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
- 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
- Health Check: Server status and metrics
- Configuration: Current settings (sanitized)
- API Test: Validate Mailcow connectivity
๐ข 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 |
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ 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 โ
โโโโโโโโโโโโโโโโโโโ
| 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 |
- CLAUDE.md - Essential context for Claude Code sessions
- Team Structure - Parallel development workflow
# 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// 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
});// 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
});// 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'
});- 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
- 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.
This project is licensed under the MIT License - see the LICENSE file for details.
- Documentation: docs/README.md
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- 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.