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

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.

Related MCP server: mcp-email

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

Tools

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

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