Skip to main content
Glama
mailu-mcp

mailu-mcp

mailu-mcp

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

CI npm License: MIT

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

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

Available Tools

32 tools
mailu_create_aliasC

Cree un alias (redirection vers une ou plusieurs destinations).

Inputs: email (required), destination (required), comment, wildcard.

mailu_create_alternativeB

Ajoute un domaine alternatif rattache a un domaine principal.

Inputs: name (required), domain (required).

mailu_create_domainC

Cree un nouveau domaine mail.

Inputs: name (required), comment, max_users, max_aliases, +3 more.

mailu_create_domain_managerB

Nomme un utilisateur gestionnaire d un domaine.

Inputs: domain (required), user_email (required).

mailu_create_relayC

Cree un relay (domaine relaye vers un SMTP cible).

Inputs: name (required), smtp, comment.

mailu_create_userC

Cree une boite mail (email + mot de passe + options).

Inputs: email (required), raw_password (required), comment, enabled, +17 more.

mailu_delete_aliasC

Supprime un alias.

Inputs: alias (required).

mailu_delete_alternativeC

Supprime un domaine alternatif.

Inputs: alt (required).

mailu_delete_domainA

Supprime un domaine (et ses boites/alias). Irreversible.

Inputs: domain (required).

mailu_delete_domain_managerB

Retire le role de gestionnaire d un domaine a un email.

Inputs: email (required), domain (required).

mailu_delete_relayC

Supprime un relay.

Inputs: name (required).

mailu_delete_userA

Supprime une boite mail. Irreversible.

Inputs: email (required).

mailu_generate_domain_dkimB

Genere (ou regenere) les cles DKIM/DMARC d un domaine.

Inputs: domain (required).

mailu_get_aliasB

Details d un alias par son adresse.

Inputs: alias (required).

mailu_get_alternativeC

Details d un domaine alternatif.

Inputs: alt (required).

mailu_get_domainC

Details d un domaine (quotas, alternatives, alias...).

Inputs: domain (required).

mailu_get_domain_managerB

Verifie si un email est gestionnaire d un domaine.

Inputs: email (required), domain (required).

mailu_get_relayC

Details d un relay par son nom.

Inputs: name (required).

mailu_get_userC

Details d une boite mail par son adresse.

Inputs: email (required).

mailu_list_aliasesA

Liste tous les alias (redirections), tous domaines confondus.

Inputs: no named parameters.

mailu_list_aliases_by_domainA

Liste les alias dont une destination appartient au domaine donne.

Inputs: domain (required).

mailu_list_alternativesB

Liste tous les domaines alternatifs.

Inputs: no named parameters.

mailu_list_domain_managersB

Liste les gestionnaires (managers) d un domaine.

Inputs: domain (required).

mailu_list_domainsB

Liste tous les domaines mail geres par Mailu.

Inputs: no named parameters.

mailu_list_domain_usersB

Liste les boites (users) d un domaine.

Inputs: domain (required).

mailu_list_relaysA

Liste tous les relays (domaines relayes).

Inputs: no named parameters.

mailu_list_usersA

Liste toutes les boites mail (users), tous domaines confondus.

Inputs: no named parameters.

mailu_requestA

Appel generique a l API Mailu (echappatoire pour tout endpoint non couvert). Fournir method, path (relatif a /api/v1) et body optionnel.

Inputs: path (required), method (required), body.

mailu_update_aliasC

Met a jour un alias (destinations, wildcard, commentaire).

Inputs: alias (required), comment, wildcard, destination.

mailu_update_domainC

Met a jour un domaine existant (quotas, commentaire, signup...).

Inputs: domain (required), comment, max_users, max_aliases, +3 more.

mailu_update_relayC

Met a jour un relay (hote SMTP, commentaire).

Inputs: name (required), smtp, comment.

mailu_update_userB

Met a jour une boite mail (mot de passe, quota, forward, reponse auto...).

Inputs: email (required), comment, enabled, enable_pop, +17 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 32 tools

    Disambiguation5/5

    Each tool targets a distinct resource-action pair (e.g., domain, user, alias, alternative, relay), with clear descriptions and no overlapping functionality. Even similar tools like list_users and list_domain_users are differentiated by scope.

    Naming Consistency5/5

    All tools follow a consistent 'mailu_{verb}_{noun}' pattern (e.g., mailu_list_domains, mailu_create_user). Verbs are action-oriented (list, get, create, update, delete, generate) and nouns correspond to resources, with no mixing of styles.

    Tool Count4/5

    32 tools is on the high side but justified by the comprehensive coverage of multiple resource types (domains, users, aliases, alternatives, relays) including managers, DKIM generation, and a generic API fallback. Could be slightly trimmed but remains well-scoped.

    Completeness5/5

    The set covers the full lifecycle for all major resources: CRUD for domains, users, aliases, alternatives, and relays, plus domain managers, DKIM generation, and a generic API call for edge cases. No obvious gaps for standard mail server management.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server that gives Claude and other MCP hosts full access to Mail.app on macOS — search, read, send, reply, flag, move, and more across all accounts configured in Mail.app.
      24
      70 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Self-hosted MCP server for any IMAP/SMTP inbox. Multi-account in one config. Built for Claude Code.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Local IMAP/SMTP MCP server that lets Claude read, search, draft, send, flag, and move mail across multiple IMAP mailboxes. Credentials stay on your machine.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A minimal MCP server for reading, searching, managing, and sending email over IMAP and SMTP.
      MIT