Fluxmail

Official

by churichard · TypeScript

Read, search, draft, send, and organize email through Gmail and IMAP/SMTP mailboxes.

packages/server/README.md3 KBView on GitHub

Fluxmail

Fluxmail is a self-hosted MCP server that connects AI agents to Gmail and IMAP/SMTP mailboxes. It gives MCP clients a consistent set of tools to read, search, draft, send, and organize email.

Install

Fluxmail requires Node.js 20.20.x, or Node.js 22.22 or later.

bash

npm install -g fluxmail

Connect Gmail

Create a Google Cloud OAuth client with the Gmail API enabled, then save its credentials:

bash

fluxmail config set GOOGLE_CLIENT_ID <your-client-id>.apps.googleusercontent.com
fluxmail config set GOOGLE_CLIENT_SECRET <your-client-secret>
fluxmail accounts add gmail

For a local installation, the last command starts Google's consent flow in your browser.

For Docker or a remote server, set FLUXMAIL_PUBLIC_URL to the server's public HTTPS address and register <FLUXMAIL_PUBLIC_URL>/auth/google/callback as an authorized redirect URI in Google Cloud. Run the command on the server, then open the printed URL in your local browser:

bash

docker compose exec fluxmail fluxmail accounts add gmail

Open the printed link, then select Continue with Google. The link expires after 10 minutes and works once. Fluxmail selects the flow from FLUXMAIL_PUBLIC_URL; --local and --hosted override that selection when needed.

Connect IMAP

bash

fluxmail accounts add imap \
  --email you@example.com \
  --imap-host imap.example.com \
  --smtp-host smtp.example.com

Fluxmail prompts for the password and stores it encrypted. Use --imap-password-env <name> for Docker or scripted setup.

Connect an MCP client

Configure your client to launch fluxmail stdio. For example, with Claude Code:

bash

claude mcp add fluxmail -- fluxmail stdio

Or with Codex CLI:

bash

codex mcp add fluxmail -- fluxmail stdio

Fluxmail also supports Streamable HTTP for Docker and remote deployments.

See the setup guide for Google OAuth configuration, Docker deployment, supported MCP clients, environment variables, and the complete tool list.

Telemetry

Fluxmail reports anonymous CLI and MCP feature usage to PostHog. It does not send command arguments, mailbox data, message content, account or message IDs, file paths, secrets, or error messages. Run fluxmail telemetry disable to turn it off. Use fluxmail telemetry status to check the setting or fluxmail telemetry enable to turn it back on. FLUXMAIL_TELEMETRY=0 and DO_NOT_TRACK=1 also disable telemetry. The telemetry reference lists every event and property.

License

See the repository for license terms.

Install

Configuration

Environment variables

GOOGLE_CLIENT_ID

Google OAuth client ID. Required only when connecting Gmail accounts.

GOOGLE_CLIENT_SECRETsecret

Google OAuth client secret. Required only when connecting Gmail accounts.

FLUXMAIL_DATA_DIR

Directory for the Fluxmail database, encryption key, and stored settings.

FLUXMAIL_LICENSE_KEYsecret

Optional Fluxmail license key for paid plan limits.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "fluxmail": {
      "command": "npx",
      "args": [
        "-y",
        "fluxmail@0.2.1",
        "stdio"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "<YOUR_GOOGLE_CLIENT_ID>",
        "GOOGLE_CLIENT_SECRET": "<YOUR_GOOGLE_CLIENT_SECRET>",
        "FLUXMAIL_DATA_DIR": "<YOUR_FLUXMAIL_DATA_DIR>",
        "FLUXMAIL_LICENSE_KEY": "<YOUR_FLUXMAIL_LICENSE_KEY>"
      }
    }
  }
}