MoltenMail agent setup guide

Click this link on the same Mac where MoltenMail is installed.

Your browser saves a file named moltenmail-cli.zip, usually in Downloads.

Optional. If you want to read the program source first, you can view the source on GitHub. The signed download is the same program, built and checked by us. You do not need GitHub to finish setup.

Your AI app will point to a fixed location. If you leave the helper in Downloads and later empty it, the connection breaks. We will move it into a folder inside your home folder.

Find your Mac short user name

You will need this in Step 4. It is the short name for your account.

1. Click the Apple menu, top left, then System Settings.
2. Click Users & Groups.
3. Under your picture you see your account name, with a shorter name below it. That short name is your user name. Example: mcmin.

Or, in Finder, press Command Shift H to open your home folder. The folder name at the end is your user name.

Open Terminal

Terminal is the Mac app for typing commands. It will not harm your Mac if you only run the commands on this page.

1. Press Command Space to open Spotlight search.
2. Type Terminal and press Return. A window opens with a blinking cursor. The line usually ends with a percent sign or a dollar sign. That is where you type.

Run these three lines, one at a time

For each line: click Copy, click inside the Terminal window, press Command V to paste, then press Return.

mkdir -p ~/.local/bin

unzip -o ~/Downloads/moltenmail-cli.zip -d ~/.local/bin/

chmod +x ~/.local/bin/moltenmail-cli

Success looks like: the first and third lines print nothing and give you a new prompt line. The middle line prints a line mentioning inflating and no error at the end.

Optional check. Run this to confirm the helper works. You should see a version number.

~/.local/bin/moltenmail-cli --version

1. Open MoltenMail.
2. Click MoltenMail in the menu bar, then Settings.
3. Open the Local Agent Access section.
4. Turn on the master switch at the top.
5. Turn on Read mail if you want the assistant to read messages.
6. Turn on Create drafts if you want the assistant to draft replies you review.

MoltenMail starts listening on your Mac as soon as the master switch is on. You do not need to restart MoltenMail.

Your AI app needs one small block of settings. Use the real path with your short user name from Step 2, not the words YOUR-USERNAME.

Example, if your user name is mcmin, the full path is:

/Users/mcmin/.local/bin/moltenmail-cli

Here is the block to add. Replace YOUR-USERNAME:

{
  "mcpServers": {
    "moltenmail": {
      "command": "/Users/YOUR-USERNAME/.local/bin/moltenmail-cli",
      "args": ["mcp"]
    }
  }
}

Path A: Claude Desktop

1. Open Claude Desktop.
2. Open Settings. On Mac this is often the Claude menu, then Settings.
3. Open Developer, or Advanced.
4. Click Edit Config, or Open config file. A text file opens.
5. If the file is empty, paste the whole block above.
6. If it already has content, find the mcpServers section and paste the moltenmail block inside it, next to your other servers. Put one comma between each server entry.
7. Save the file.

Path B: LM Studio

1. Open LM Studio.
2. Open the settings for MCP or Integrations. Follow the label in your version of LM Studio.
3. Open the MCP server config file it shows, or add a server entry in the interface if it offers one.
4. Paste the same block, with your user name in the path.
5. Save.

Path C: Any other MCP-capable app

1. Open that app documentation for MCP server setup.
2. Find where it asks for a server command and arguments, or a JSON mcpServers block.
3. Paste the same block, or enter the command /Users/YOUR-USERNAME/.local/bin/moltenmail-cli with the argument mcp.
4. Save.

If your app asks for a single command line instead of JSON, open Connect an agent in MoltenMail. It shows the exact command for your tool.

Most AI apps read the MCP settings only when they start. Closing the chat window is not enough.

1. Click the app name in the menu bar, next to the Apple menu.
2. Click Quit. Or press Command Q while the app is active.
3. Open the app again from Applications or Spotlight.

Part A: check from Terminal

This proves the whole path: helper, to MoltenMail, to your mailbox.

~/.local/bin/moltenmail-cli accounts list

Success looks like: text that lists your email accounts.

Part B: check inside your AI app

1. Open your AI app after the restart in Step 5.
2. Look for MoltenMail in its list of tools or MCP servers. The wording varies by app.
3. Ask a plain question, such as: List my email accounts using MoltenMail.
4. You should see the same accounts as in Part A, plus tools for folders, reading mail, and creating drafts.

If Part A works but the app does not: check your user name in the command path, check that you fully quit and reopened, and check that you did not replace the whole config file and remove other servers.