Skip to main content
Glama

mai (Mail for AI)

TIP

Are you new to mai? Readmai for a new user. It tells the functions of mai in words that are not technical.

mai is a mail server for agents. Each agent gets a mailbox. The agents send requests, replies and status to each other through MCP tools.

The container has PostgreSQL, Dovecot (IMAP), Postfix (SMTP) and the app. The app is an MCP server and an optional mail UI. The mail domain is mai.internal.

mai operates on macOS, Linux and Windows. All the servers are in one Linux container. On the host, one binary, mai, operates the container through the Engine API. You do not use docker, podman, or compose.

NOTE

mai 3.0 is not compatible with 2.x. It uses new volumes and does not read 2.x data. Refer toCHANGELOG.md.

Requirements

Host

Necessary software

macOS

Docker Desktop or Podman

Windows

Docker Desktop with the WSL 2 back end. Refer to Run mai on Windows.

Linux

Docker Engine or Podman

The CLI does not install an engine. If no engine is installed, mai start stops and gives the install step for your OS.

Related MCP server: imap-smtp-mcp

Quick start

  1. Install the CLI with Go 1.27 or a newer version:

    go install github.com/monorithm/mai/cli/v3/cmd/mai@latest

    Go puts mai in the folder bin of go env GOPATH. Make sure that this folder is in your PATH. On macOS, install the Xcode command line tools first (xcode-select --install). The move of the keys of mai 3.0 and 3.1 from the keychain of macOS uses cgo, and cgo must have a C compiler.

    An AI agent in your app can do steps 2 to 4 after your approval in the chat, when you tell it "Run mai guide, and connect this app to mai."

  2. Start mai:

    mai start

    The CLI finds the engine and starts it if it is stopped. It pulls the image ghcr.io/monorithm/mai of its own version, makes the container, and waits until the container is healthy. At the first start, it makes the owner key and keeps it in its key file.

  3. Add an agent:

    mai agent add cursor

    The CLI keeps the agent key in its key file, with the mode 0600. It does not show the key.

  4. Connect an app to the agent:

    mai connect cursor --agent cursor

    The CLI shows the change to the MCP entry and the hooks of the app. It writes the change only after you agree. The MCP entry is mai mcp --agent cursor, and it holds no secret. The apps are claude, cursor, copilot, codex, and antigravity.

  5. Start the app. The app starts mai mcp, and the bridge gets a lease with the agent key.

  6. Optional: start the mail UI and open it:

    mai ui on
    mai ui open

    mai ui open signs you in to the UI in your browser. mai ui off stops the UI. The UI is off by default.

  7. To remove mai and all the items that it made:

    mai uninstall
    CAUTION

    mai uninstall deletes all mail and all copies. To keep a copy, add --backup PATH.

Lifecycle commands

Command

Action

mai start

Start the container. Make it if it does not exist.

mai stop

Stop the container. The volumes stay.

mai status

Show the health, the versions, the engine, the port, and the state of the UI.

mai logs --follow

Show the log of the container.

mai doctor

Examine the engine, the port, the disk space, the key file, and the keychain items of mai 3.0 and 3.1.

mai upgrade

Move the keys from the keychain of mai 3.0 and 3.1 to the key file. Pull the image of the new CLI version and make the container again.

The image

The image is ghcr.io/monorithm/mai in the GitHub Container Registry. The image is public. For a pull, a login and a token are not necessary. The CLI pulls the image with the same version as the CLI.

Data

The volume mai3-data holds the data of mai: the database, the mail, and the backups. The volume mai3-spool holds the Postfix queue. To keep the data in a folder on the host, use mai start --data-dir PATH. The CLI writes the choice to its configuration file.

Addresses on the host

Address

Service

http://127.0.0.1:8765

MCP (/mcp), API (/api), and the optional mail UI (/ui)

The container publishes no IMAP port and no submission port. The agents use only MCP.

Documentation

Refer to docs/README.md.

Development

A clone is necessary only to change mai. The server is Python with uv. The host CLI is Go, in the folder cli/.

These commands make the image from the Dockerfile:

docker build --pull=false -t mai:dev .

These commands run the tests of the server and install the hooks:

uv sync
uv run pytest -q
lefthook install

These commands build and test the CLI:

cd cli
go build ./...
go vet ./...
go test ./...

Agents that change this project must use the skill mai-dev. Refer to the skill file.

License

Apache License 2.0. Copyright 2026 Moses Gameli. Refer to LICENSE and NOTICE.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides AI agents with a persistent, agent-native email mailbox for sending, receiving, and managing emails through bounded-context retrieval, idempotent operations, and explicit acknowledgement.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes any IMAP mailbox and SMTP relay as MCP tools, enabling email management (read, search, send, delete) through MCP-compatible agents.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides asynchronous messaging infrastructure for AI agents, enabling them to get permanent addresses and send/receive encrypted messages via MCP tools.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to send and receive signed/encrypted mail at agent@domain addresses, manage store-and-forward mailboxes, and operate a double-entry ledger with escrow and bond contracts through MCP tools.
      398 npm
      Apache 2.0