mailu-mcp

MCP server to administer a Mailu mail server from Claude — domains, mailboxes, aliases and forwards, without leaving the conversation.

Installation · Tools · Examples · 🇫🇷 Français

Overview

This MCP server exposes Mailu's admin REST API as tools Claude can call. Ask in natural language, Claude executes:

You: List the domains managed by Mailu, then the aliases of example.com.

Claude: (calls mailu_list_domains then mailu_list_aliases_by_domain) 3 domains: example.com, example.org, example.net. Aliases of example.com: contact@ → [email protected], info@ → [email protected].

Requirements

Enable the REST API on the Mailu server (mailu.env, Mailu ≥ 1.9, tested on 2.0):

API=true
WEB_API=/api
API_TOKEN=<generate with: openssl rand -hex 32>

Then recreate the containers: cd /mailu && docker compose up -d. Verify: curl -H "Authorization: <API_TOKEN>" https://mail.example.com/api/v1/domain.

Auth: the token goes raw in the Authorization header (apiKey scheme, no Bearer prefix).

Installation

Claude Code

claude mcp add mailu \
  --env MAILU_API_URL=https://mail.example.com/api/v1 \
  --env MAILU_API_TOKEN=your_token \
  -- npx -y @manganate06/mailu-mcp

Claude Desktop / Cursor

Add to claude_desktop_config.json (or Cursor's MCP config):

{
  "mcpServers": {
    "mailu": {
      "command": "npx",
      "args": ["-y", "@manganate06/mailu-mcp"],
      "env": {
        "MAILU_API_URL": "https://mail.example.com/api/v1",
        "MAILU_API_TOKEN": "your_token"
      }
    }
  }
}

Tested with Claude Code and Claude Desktop.

Configuration

| Variable | Purpose | Required | Where to get it | |---|---|---|---| | MAILU_API_URL | API base URL (with /api/v1) | ✅ | your Mailu instance | | MAILU_API_TOKEN | API token | ✅ | API_TOKEN in mailu.env | | MAILU_MCP_DEBUG | Debug logs on stderr | ❌ | true / false |

Tools

32 tools, mailu_ prefix (omitted in the table). Parameter details: src/index.ts.

| Area | Tools | |---|---| | Domains | list_domains, get_domain, create_domain, update_domain, delete_domain, generate_domain_dkim, list_domain_users, list_domain_managers, create_domain_manager, get_domain_manager, delete_domain_manager | | Mailboxes | list_users, get_user, create_user, update_user, delete_user | | Aliases | list_aliases, get_alias, list_aliases_by_domain, create_alias, update_alias, delete_alias | | Alternatives | list_alternatives, get_alternative, create_alternative, delete_alternative | | Relays | list_relays, get_relay, create_relay, update_relay, delete_relay | | Generic | mailu_request (method, path, body) — escape hatch for any endpoint |

Examples

• "List the Mailu domains"
• "Show the aliases of example.com"
• "Create the mailbox [email protected] with a 2 GB quota"
• "Add an alias [email protected] forwarding to [email protected]"
• "Regenerate the DKIM keys for example.com"

Transport

stdio — works with Claude Code, Claude Desktop, Cursor and any MCP client.

Development

git clone https://github.com/manganate006/mailu-mcp
cd mailu-mcp && npm install
npm run build && npm run bundle    # dist/bundle.js (single file, e.g. for NFS)
npm test                           # CRUD self-test (needs live MAILU_API_URL/TOKEN)
npx @modelcontextprotocol/inspector node dist/bundle.js

License

MIT