Submit
manganate006

mailu-mcp

Community manganate006
Updated

MCP server to administer a Mailu mail server from Claude — domains, mailboxes, aliases, relays — via its admin REST API. 32 tools, TypeScript.

mailu-mcp

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

CInpmLicense: 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@ → [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

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

MCP Server · Populars

MCP Server · New