Quickstart

Fluxmail is a self-hosted MCP server that connects AI agents to your email. It runs on your machine or a server you control, talks to Gmail through a Google OAuth app that you own, and gives any MCP client the same tools to read, search, draft, send, and organize mail over stdio or Streamable HTTP.

This guide takes you from nothing to a working setup: install the CLI, create Google credentials, connect Gmail, and register the server with your agent.

What you need

• Node.js 20.19 or newer
• A Google account
• An MCP client such as Claude Code, Claude Desktop, ChatGPT, Codex, Cursor, Gemini CLI, Hermes, or VS Code

1. Install Fluxmail

npm install -g fluxmail

Check that your shell can find it:

which fluxmail

Keep that path handy. Some desktop apps start with a limited PATH; if your client cannot find fluxmail, use the absolute path returned by this command.

2. Create Google OAuth credentials

Fluxmail talks to Gmail through your own Google Cloud OAuth app, so the API quota and the consent screen are yours.

1. Open Google Cloud Console and create or select a project.
2. Go to APIs & Services → Library and enable the Gmail API.
3. Configure the OAuth consent screen. Choose External, then add yourself and anyone else who will connect an account as test users. Testing mode is fine for self-hosting; Google does not require verification for up to 100 test users.
4. Go to Credentials → Create credentials → OAuth client ID.
5. Choose Web application and add these authorized redirect URIs:
   • http://localhost:8976/oauth/callback (used by fluxmail accounts add gmail)
   • <your FLUXMAIL_PUBLIC_URL>/auth/google/callback (only if you use the server-hosted flow on a remote deployment)

Fluxmail requests the full https://mail.google.com/ scope because its email API supports permanent deletion, which Gmail's narrower scopes do not allow.

While your consent screen is in Google's "Testing" status, refresh tokens expire seven days after they are issued, even if Fluxmail uses them during that window. When a token expires, find the account ID with fluxmail accounts list, then reconnect it:

fluxmail accounts add gmail --reauthorize <account-id>

To avoid the seven-day expiry, publish the consent screen to "In production" for long-lived tokens.

3. Run Fluxmail and connect Gmail

There are two ways to run the server. Pick one.

Option A: local process (stdio)

The shortest path for personal use on one machine.

# Store your Google credentials once; they live in ~/.fluxmail/config.env
fluxmail config set GOOGLE_CLIENT_ID <your-client-id>.apps.googleusercontent.com
fluxmail config set GOOGLE_CLIENT_SECRET <your-client-secret>

# Connect your Gmail (opens a browser consent flow)
fluxmail accounts add gmail

Option B: Docker (Streamable HTTP server)

For a shared or remote deployment. The image is published to GitHub Container Registry as ghcr.io/churichard/fluxmail-mcp for amd64 and arm64.

mkdir fluxmail && cd fluxmail
curl -fsSLO https://raw.githubusercontent.com/churichard/fluxmail-mcp/main/docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/churichard/fluxmail-mcp/main/.env.example -o .env
# Fill in GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET in .env

docker compose up -d

# Create an API key (shown once). Name it after the client that will use it, e.g. "laptop".
docker compose exec fluxmail fluxmail apikey create --name laptop

# Connect your Gmail: prints a consent URL; open it in your browser
docker compose exec fluxmail fluxmail accounts add gmail

4. Connect your agent

Follow the subsection matching how you ran Fluxmail in step 3.

Option A: stdio clients

Every client launches the same command: fluxmail stdio. Your Google credentials come from fluxmail config set, so the snippets need no environment variables. Two notes:

• Desktop apps sometimes launch with a minimal PATH and fail to find fluxmail (common with nvm installs). If that happens, use the absolute path from which fluxmail as the command.
• If you skipped fluxmail config set, add GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET to the client's env settings instead.

claude mcp add fluxmail -- fluxmail stdio

{
  "mcpServers": {
    "fluxmail": {
      "command": "fluxmail",
      "args": ["stdio"]
    }
  }
}

codex mcp add fluxmail -- fluxmail stdio

[mcp_servers.fluxmail]
command = "fluxmail"
args = ["stdio"]

{
  "mcpServers": {
    "fluxmail": {
      "command": "fluxmail",
      "args": ["stdio"]
    }
  }
}

mcp_servers:
  fluxmail:
    command: 'fluxmail'
    args: ['stdio']

{
  "mcpServers": {
    "fluxmail": {
      "command": "fluxmail",
      "args": ["stdio"]
    }
  }
}

{
  "servers": {
    "fluxmail": {
      "type": "stdio",
      "command": "fluxmail",
      "args": ["stdio"]
    }
  }
}

Option B: Streamable HTTP clients

Every client connects to http://localhost:8977/mcp (or your deployed URL) and authenticates with the header Authorization: Bearer fmk_..., using the API key from step 3.

claude mcp add --transport http fluxmail http://localhost:8977/mcp \
  --header "Authorization: Bearer fmk_..."

[mcp_servers.fluxmail]
url = "http://localhost:8977/mcp"
http_headers = { Authorization = "Bearer fmk_..." }

{
  "mcpServers": {
    "fluxmail": {
      "url": "http://localhost:8977/mcp",
      "headers": { "Authorization": "Bearer fmk_..." }
    }
  }
}

mcp_servers:
  fluxmail:
    url: 'http://localhost:8977/mcp'
    headers:
      Authorization: 'Bearer fmk_...'

{
  "mcpServers": {
    "fluxmail": {
      "httpUrl": "http://localhost:8977/mcp",
      "headers": { "Authorization": "Bearer fmk_..." }
    }
  }
}

{
  "servers": {
    "fluxmail": {
      "type": "http",
      "url": "http://localhost:8977/mcp",
      "headers": { "Authorization": "Bearer fmk_..." }
    }
  }
}

Once it's connected, ask your agent something like "What's the latest email from my bank?" to confirm it works.

Next steps

• See Tools for the full tool set your agent can call.
• See Configuration for environment variables.
• See CLI reference for every fluxmail command.
• See Teams & plans for members, shared mailboxes, and paid-plan licensing.
• See Architecture for where your data lives and how Fluxmail is built.