MCP Mailu Server

A FastMCP server for integrating with Mailu email server administration using the official Mailu REST API.

This server automatically converts the entire Mailu API into MCP tools and resources, providing seamless integration between AI assistants and your Mailu mail server.

Features

🔧 Automatically Generated Tools (from Mailu API)

• User Management: Create, update, delete, and find users
• Domain Management: Create, update, delete, and find domains
• Alias Management: Create, update, delete, and find email aliases
• DKIM Operations: Generate DKIM keys for domains
• Manager Operations: Assign and manage domain managers

📊 Automatically Generated Resources

• Users: GET /user - List all users
• Domains: GET /domain - List all domains
• Aliases: GET /alias - List all aliases
• Domain Users: GET /domain/{domain}/users - List users for specific domain
• User Details: GET /user/{email} - Get specific user information
• Domain Details: GET /domain/{domain} - Get specific domain information

⚡ Key Benefits

• Complete API Coverage: Every Mailu API endpoint automatically available
• Type Safety: Full TypeScript-like type checking with Pydantic models
• Smart Resource Mapping: GET requests become Resources, modifications become Tools
• Authentication Handled: Bearer token authentication built-in
• Error Handling: Comprehensive error responses and validation

Installation

From PyPI (Recommended)

# Install from PyPI
pip install mcp-mailu

# Or with uv
uv add mcp-mailu

From Source

This project uses uv for dependency management.

# Clone and navigate to the project
git clone https://git.supported.systems/MCP/mcp-mailu.git
cd mcp-mailu

# Install dependencies
uv sync

# Install in development mode
uv pip install -e .

Configuration

1. Get Your Mailu API Token

First, you need to obtain an API token from your Mailu instance:

1. Log into your Mailu admin interface
2. Go to the API section
3. Generate a new API token
4. Copy the token for configuration

2. Set Environment Variables

Copy the example configuration:

cp .env.example .env

Edit .env and set your values:

# Your Mailu server URL (without /api/v1)
MAILU_BASE_URL=https://mail.yourdomain.com

# Your Mailu API token
MAILU_API_TOKEN=your_actual_token_here

# Optional: Enable debug logging
DEBUG=true

3. Alternative: Environment Variables

You can also set environment variables directly:

export MAILU_BASE_URL="https://mail.yourdomain.com"
export MAILU_API_TOKEN="your_token_here"

Usage

Running the Server

# Using uv
uv run mcp-mailu

# Or directly with Python
python -m mcp_mailu.server

# With environment variables
MAILU_BASE_URL="https://mail.example.com" MAILU_API_TOKEN="token" uv run mcp-mailu

Available Operations

The server automatically exposes all Mailu API operations. Here are some examples:

User Operations

• create_user - Create a new email user with password, quota, and settings
• update_user - Update user settings, password, or quota
• delete_user - Remove a user account
• find_user - Get detailed user information
• list_users - Get all users across all domains

Domain Operations

• create_domain - Add a new email domain
• update_domain - Modify domain settings and quotas
• delete_domain - Remove a domain (and all its users)
• find_domain - Get domain details including DNS settings
• list_domain - Get all domains
• generate_dkim - Generate new DKIM keys for a domain

Alias Operations

• create_alias - Create email aliases with multiple destinations
• update_alias - Modify alias destinations or settings
• delete_alias - Remove email aliases
• find_alias - Get alias details
• list_alias - Get all aliases

Examples with Parameters

Create a new user:

{
  "email": "john.doe@example.com",
  "raw_password": "SecurePassword123!",
  "displayed_name": "John Doe",
  "quota_bytes": 2000000000,
  "enabled": true,
  "comment": "Sales team member"
}

Create a domain:

{
  "name": "newcompany.com",
  "max_users": 50,
  "max_aliases": 100,
  "signup_enabled": false,
  "comment": "New company domain"
}

Create an alias:

{
  "email": "sales@example.com",
  "destination": ["john@example.com", "jane@example.com"],
  "comment": "Sales team alias"
}

Development

Setup Development Environment

# Install with development dependencies
uv sync --dev

# Run tests
uv run pytest

# Format code
uv run black src/
uv run ruff check src/ --fix

# Type checking
uv run mypy src/

Project Structure

src/
├── mcp_mailu/
│   ├── __init__.py           # Package initialization
│   └── server.py             # Main FastMCP server with OpenAPI integration
├── .env.example              # Configuration template
├── scripts/                  # Build and publish scripts
├── pyproject.toml            # UV project configuration
├── README.md                 # This file
└── .gitignore               # Git ignore rules

Publishing to PyPI

The project includes scripts for easy PyPI publishing:

# Build the package
python scripts/publish.py --build

# Check package validity
python scripts/publish.py --check

# Upload to TestPyPI for testing
python scripts/publish.py --test

# Upload to production PyPI
python scripts/publish.py --prod

Before publishing:

1. Update version in pyproject.toml and src/mcp_mailu/__init__.py
2. Update author information in pyproject.toml
3. Set up PyPI credentials with uv run twine configure

How It Works

This server uses FastMCP's from_openapi method to automatically convert the Mailu REST API into an MCP server:

1. OpenAPI Conversion: The Mailu API OpenAPI/Swagger specification is used to generate MCP tools and resources
2. Smart Mapping: GET requests become MCP Resources for data retrieval, while POST/PATCH/DELETE become Tools for actions
3. Authentication: Bearer token authentication is automatically handled for all requests
4. Type Safety: All request/response models are automatically validated using Pydantic

Troubleshooting

Common Issues

Authentication Errors:

• Verify your MAILU_API_TOKEN is correct
• Check that the token has sufficient permissions
• Ensure your Mailu instance has the API enabled

Connection Errors:

• Verify MAILU_BASE_URL is correct and accessible
• Check firewall settings and network connectivity
• Ensure HTTPS is properly configured if using SSL

Permission Errors:

• Ensure your API token has admin privileges
• Check that the specific domain/user operations are permitted

Debug Mode

Enable debug logging to troubleshoot issues:

DEBUG=true uv run mcp-mailu

API Reference

The server exposes the complete Mailu API. For detailed parameter information, refer to:

• Mailu Official Documentation
• Mailu API Swagger Specification

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

This project is licensed under the MIT License.