The master key
After this page, you know where your master key is, how to set it, how to make a key file, and how to change the master key. The master key is the key that protects the passwords that email-mcp stores.
What the master key does
email-mcp encrypts each password with AES-256-GCM (a standard encryption method that also detects changes). The keys that do this are themselves encrypted with a master key. The master key is never stored in the database.
The environment variable EMAIL_MCP_KEK says where the master key is. An
environment variable is a named setting that a program reads from its
surroundings. KEK means “key encryption key”. There is no config file: every
start of email-mcp reads this variable.
| Value | Meaning |
|---|---|
not set, or keychain |
The default. A random key in the keychain of your operating system (its password store): service email-mcp, account master-key. |
file:<absolute path> |
A key file with mode 0600 (only you can read it). Use it where there is no keychain, for example on WSL (Windows Subsystem for Linux) or on a server over SSH (Secure Shell: a way to log in to another computer over a network). An absolute path is the full path of a file. The sign ~ (your home folder) is not part of a full path, so do not use it. |
Which master key do you use?
Run this in a terminal (a window where you type commands). The command checks the install, and one of its lines names your master key:
email-mcp doctor
The line looks like one of these:
master key (keychain): ok
master key (file:/home/you/.email-mcp.key): ok
The text in the brackets is the value of EMAIL_MCP_KEK that doctor used.
keychain means that the master key is in the keychain. file: and a path
mean that the master key is in that key file. doctor reads the variable in
your terminal. It does not read the config of your AI app. If your AI app
config sets EMAIL_MCP_KEK, set the same value in the terminal before you run
doctor (see the next section). Otherwise doctor looks in the keychain.
If doctor stops before this line, because the data folder or the database file
does not exist, email-mcp has not opened that folder yet. The data folder is
the folder where email-mcp keeps its data (see Where the data
lives). See The data folder does not
exist. The
page Troubleshooting explains every
other line.
Set EMAIL_MCP_KEK
Every program that uses the same data folder needs the same setting. So set the variable in your terminal, and in the config of each AI app that starts email-mcp.
In a terminal on macOS and Linux, this command sets the variable. export
makes the setting available to the programs that you start from this terminal.
The setting lasts until you close the terminal window. The path is an example:
use the full path of your own key file.
export EMAIL_MCP_KEK=file:/home/you/.email-mcp.key
On Windows, use this line in the Command Prompt:
set EMAIL_MCP_KEK=file:C:\Users\you\.email-mcp.key
In PowerShell, use this line:
$env:EMAIL_MCP_KEK = "file:C:\Users\you\.email-mcp.key"
In the config of an AI app, the setting goes in the env block of the server.
Each page below has the step for its app, in the section “If your master key is
a file”: Claude Code,
Claude Desktop,
Cursor, VS
Code and Codex
CLI.
When Claude Code starts the server, pass the variable there too. The page Claude Code names the source and the date of this command:
claude mcp add --scope user --env EMAIL_MCP_KEK=file:/home/you/.email-mcp.key \
--transport stdio email -- email-mcp serve
(Put another flag, such as --transport stdio, between --env and the server
name. Otherwise Claude Code reads the name as another variable.)
If doctor says that the value is not valid, see the entry “The value of
EMAIL_MCP_KEK is not valid” of Troubleshooting.
The key file
The format
A key file is a text file. It holds the master key as base64 text. Base64 is a
way to write bytes with letters, digits, +, / and =. The key has exactly
32 bytes, so the text has exactly 44 characters, and the last one is =. Spaces
and empty lines before and after the text are allowed. A line break inside the
text is not.
email-mcp refuses a file with other content. For example, a file with 32 raw bytes, a file with a key in hex (letters and digits from 0 to 9 and a to f), an empty file, or a short text. See The master key file is not valid.
The mode 0600 rule
The mode of a file says who may read and write it. On macOS and Linux, a key file must have mode 0600, or a stricter mode, such as 0400. Mode 0600 means that you can read and write the file, and nobody else has any access to it. email-mcp refuses a key file when any other user of the computer has access to it. A file with mode 0644 is refused, for example. Windows has no such modes, so email-mcp does not check the mode there. On Windows, keep the key file in a folder that only your user account can read.
The command ls -l shows the mode in its first column. -rw------- is mode
0600 (a macOS system may add a sign @ after it). To fix a wrong mode, run
chmod 600 and the path of the file. chmod changes the mode of a file. See
the entry “The master key file has the wrong mode” of Troubleshooting.
Make a key file
There are two ways. Both work only for a data folder that has no stored keys yet, for example the folder of a new install. A data folder with stored keys needs the key that protects them. A new key could never open them. To change the master key of such a folder, use the rotation below.
-
Let email-mcp make the file. Set
EMAIL_MCP_KEKtofile:and a path where no file exists. The folder of the path must exist. Then run a command that opens the data, such asemail-mcp account list. email-mcp makes the file with mode 0600, and it writes a log line with the textapp: made a new master key fileto standard error (the place where a program writes messages about itself: your terminal shows it). -
Make the file yourself, on macOS and Linux. This command writes 32 random bytes as base64 text.
openssl rand -base64 32makes the text.opensslis the command of OpenSSL (a toolkit of encryption programs).>writes the text to the file.umask 077makes new files that only you can read, and the round brackets keep this setting inside this one command. The path is an example:(umask 077; openssl rand -base64 32 > /home/you/.email-mcp.key)The command prints nothing. To check the file, run these two commands. The first column of
ls -lmust start with-rw-------.wc -c(wccounts the content of a file, and-ccounts bytes) must print 45: the 44 characters of the key and the line break:ls -l /home/you/.email-mcp.key wc -c < /home/you/.email-mcp.key
Without the master key, email-mcp cannot open the stored passwords. See The master key is the wrong one.
Change the master key
email-mcp key rotate moves to a new master key. To rotate a key means to
replace it with a new one. The command re-encrypts only the wrapped keys (the
keys that protect your passwords, each one encrypted with the master key), so it
is quick. It does not change your mail passwords. If the old master key may have
leaked, read the last paragraph of this section too.
-
Stop every program that uses the data folder:
serve,setup, and the AI apps that start email-mcp. -
Run the rotation. Run only one of the two commands below, the one that fits the master key that you want. To change to a new key file (it must not exist yet), run this command:
email-mcp key rotate --to file:/home/you/.email-mcp-2.keyTo change to the keychain, run this command instead:
email-mcp key rotate --to keychainEither command asks you to confirm that every other program is stopped. Without a terminal, add
--yes. -
It prints the new
EMAIL_MCP_KEKsetting. Use it everywhere from now on, also in theenvof your AI app config. -
Run
email-mcp doctorwith the new setting. When it passes, you may delete an old key file. The command never deletes the old keychain entry, because another data folder may use it.
The command makes the new key file itself, with mode 0600, and it never
overwrites a file: when a file exists at the path, it stops and changes nothing.
When the command works, it prints “The master key was changed. Every stored key
is now wrapped by the new master key”, and then the new setting to use from now
on. The page Commands lists the flags of key rotate.
If the old master key may have leaked, also change the mail passwords at your mail provider. Then reconnect each account with its new password (see Reconnect an account).