<div align="center">

mailu-mcp

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

Installation · Tools · Examples · Limitations · 🇫🇷 Français

</div>

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@ → team@gmail.com, info@ → team@gmail.com.

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 contact@example.com with a 2 GB quota"
• "Add an alias info@example.com forwarding to jean@gmail.com"
• "Regenerate the DKIM keys for example.com"

Limitations

• Mirrors the Mailu admin REST API — anything the API doesn't expose (fetched accounts, webmail/antispam settings…) isn't available; reach any un-wrapped endpoint via mailu_request.
• No bulk helpers — one object per call (the assistant can loop over a list).
• MAILU_API_TOKEN is a full-admin credential — scope it and restrict network access to the API.

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                           # unit tests (mocked HTTP, no live server)
npm run test:integration           # end-to-end CRUD self-test (needs live MAILU_API_URL/TOKEN)
npx @modelcontextprotocol/inspector node dist/bundle.js

License

MIT