mailu-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mailu-mcp Show aliases for example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_domainsthenmailu_list_aliases_by_domain) 3 domains:example.com,example.org,example.net. Aliases ofexample.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
Authorizationheader (apiKey scheme, noBearerprefix).
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-mcpClaude 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 |
| API base URL (with | ✅ | your Mailu instance |
| API token | ✅ |
|
| Debug logs on stderr | ❌ |
|
Tools
32 tools, mailu_ prefix (omitted in the table). Parameter details: src/index.ts.
Area | Tools |
Domains |
|
Mailboxes |
|
Aliases |
|
Alternatives |
|
Relays |
|
Generic |
|
Examples
"List the Mailu domains"
"Show the aliases of
example.com""Create the mailbox
contact@example.comwith a 2 GB quota""Add an alias
info@example.comforwarding tojean@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_TOKENis 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.jsLicense
Available Tools
32 toolsmailu_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
Scored across 32 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for MailTempo's public free temporary email inboxes.
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Your mailbox for MCP clients: search, read, draft, send, rules and notes. Sending is off by default.
MCP server for Nylas — read email, calendars, events and contacts, and send email or create events.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP 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.2470 npm1MIT
- FlicenseNot gradedqualityDmaintenanceSelf-hosted MCP server for any IMAP/SMTP inbox. Multi-account in one config. Built for Claude Code.-
- FlicenseNot gradedqualityCmaintenanceLocal IMAP/SMTP MCP server that lets Claude read, search, draft, send, flag, and move mail across multiple IMAP mailboxes. Credentials stay on your machine.-
- AlicenseNot gradedqualityDmaintenanceA minimal MCP server for reading, searching, managing, and sending email over IMAP and SMTP.MIT