Documentation/AI agents & assistants/Claude Desktop

Using MailFlat with Claude Desktop

Add the MailFlat MCP server to Claude Desktop so Claude can open a real inbox, read the verification code your app just sent, and clean up afterwards.

How it fits together

Claude Desktop reads one JSON file at startup and launches every MCP server listed in it. Once MailFlat is in that file you stop copying addresses by hand: you ask for a code, Claude opens the inbox, waits for the mail and reads the code back to you in the same message.

Install the runner

uvx runs the server in a throwaway environment, so nothing lands in your system Python. pipx is the equivalent if you would rather install it once.

Shell

brew install uv          # macOS
# or, if you already use pipx:
pipx install mailflat-mcp

Open the config file

Claude Desktop creates it the first time you add a server, so it may not exist yet — create it with the JSON from the next step.

Shell

# macOS
open "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
 
# Windows (PowerShell)
notepad $env:APPDATA\Claude\claude_desktop_config.json
 
# Linux
xdg-open ~/.config/Claude/claude_desktop_config.json

Add MailFlat

Keep any servers already in mcpServers — this is one entry alongside them, not a replacement for the file.

JSON

{
  "mcpServers": {
    "mailflat": {
      "command": "uvx",
      "args": ["mailflat-mcp"],
      "env": { "MAILFLAT_API_KEY": "mf_live_..." }
    }
  }
}

Quit Claude Desktop completely and reopen it — closing the window is not enough; MCP servers only start at launch.

Prove the command works before blaming the app

Run exactly what the config runs. If this prints nothing and waits, the server started correctly — that silence is the stdio protocol, not a hang. Press Ctrl+C.

Shell

MAILFLAT_API_KEY=mf_live_... uvx mailflat-mcp

If Claude cannot find uvx

A desktop app does not inherit your shell PATH, so a command that works in your terminal can still be missing here. Give the absolute path from `which uvx`.

JSON

{
  "mcpServers": {
    "mailflat": {
      "command": "/opt/homebrew/bin/uvx",
      "args": ["mailflat-mcp"],
      "env": { "MAILFLAT_API_KEY": "mf_live_..." }
    }
  }
}

Worth knowing

Claude asks before each tool call the first time. delete_inbox is irreversible and the messages are gone with it, so read what it is about to delete rather than approving on autopilot.

The key sits in a plain-text file in your home directory. Use a key created for this machine and revoke it from Agents if the laptop leaves your hands.

Ask for a short retention when you only need one code: an inbox opened with retention_hours 2 empties itself even if nobody remembers to call delete_inbox.

If Claude keeps reporting that no code arrived, check whether the inbox is end-to-end encrypted. The server cannot read those, so it has no code to hand back — and the tool can only say it failed, not why. Let Claude open its own unencrypted inbox instead of pointing it at one of yours.

Using MailFlat with Claude Desktop

How it fits together

Install the runner

Open the config file

Add MailFlat

Prove the command works before blaming the app

If Claude cannot find uvx

Worth knowing

See also