mcp-mailcow

Model Context Protocol server for Mailcow. Pilot your Mailcow instance from Claude (or any MCP-compatible client): read/send mail, manage mailboxes, aliases, domains, app passwords.

This is a BYOK (Bring Your Own Keys) package — install it on your own machine, point it at your Mailcow, use your credentials.

Features

User mode (mailbox operations)

• Read inbox, search messages, download attachments
• Send mail, reply to messages
• Mark read/unread/flagged, move, delete

Admin mode (server operations)

• Manage mailboxes (create / list / update / delete / quota)
• Manage aliases (create / list / delete)
• Manage domains (list / create)
• Manage app passwords (list / create / delete with protocol scoping)
• Quota reports, deliverability tests, server status

Install

Python (recommended)

# Zero-install with uvx (recommended)
uvx mcp-mailcow --mode user

# Or pip install
pip install mcp-mailcow

Node / TypeScript

npm install -g mcp-mailcow
# or use npx
npx mcp-mailcow --mode user

Configuration

Claude Desktop / Claude Code

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mailcow-mailbox": {
      "command": "uvx",
      "args": ["mcp-mailcow", "--mode", "user"],
      "env": {
        "MAILCOW_HOST": "mail.example.com",
        "MAILCOW_MAIL_USER": "you@example.com",
        "MAILCOW_MAIL_PASS": "your-app-password"
      }
    },
    "mailcow-admin": {
      "command": "uvx",
      "args": ["mcp-mailcow", "--mode", "admin"],
      "env": {
        "MAILCOW_ADMIN_URL": "https://mail.example.com",
        "MAILCOW_ADMIN_API_KEY": "your-api-key"
      }
    }
  }
}

You can run both modes simultaneously (each gets its own server entry).

Environment variables

User mode

Admin mode

Common

Security best practices

1. Use app passwords, not your main mailbox password. In Mailcow: mailbox → app passwords → create, scope to IMAP+SMTP only.

2. Use a Read-Only API key for admin mode if you only need to query. (Set API_KEY_READ_ONLY instead of API_KEY in mailcow.conf.)

3. Audit log review: tail ~/.local/state/mcp-mailcow/audit.log periodically.

4. Destructive operations (mailbox_delete, alias_delete) require an explicit confirm: true parameter. The server refuses without it.

Development

This is a monorepo with parallel Python and TypeScript implementations. Both share a common tool schema (tools-schema.yaml) as source of truth.

mcp-mailcow/
├── tools-schema.yaml       ← source of truth (read by both impls at build time)
├── py/                     ← Python implementation (PyPI)
├── node/                   ← TypeScript implementation (npm)
└── shared/                 ← shared mocks, integration tests

See CONTRIBUTING.md for setup and contribution guidelines.

License

MIT — see LICENSE.