Commands
After this page, you can find the command for a task, and you know its flags. You run each command in a terminal (a window where you type commands).
The commands
Write email-mcp, then the name of the command. The commands serve and
setup keep running until you press Ctrl-C (hold the Ctrl key and press C). The
other commands end when they are done.
| Command | What it does |
|---|---|
email-mcp serve |
Serves MCP (Model Context Protocol: an open standard that lets AI apps call tools that other programs offer) over stdio (standard input and output: the AI app starts the program and talks to it directly, with no network). This is what AI apps run. See Connect an AI app. |
email-mcp serve --http 127.0.0.1:8765 |
Serves MCP over local HTTP (HyperText Transfer Protocol: the protocol that apps and browsers use to talk over a network) at /mcp. See Local HTTP mode. |
email-mcp setup |
Signs your browser in to the local web pages (the pages that email-mcp shows in your browser, from your own computer), and serves them until Ctrl-C. See Connect your first account. |
email-mcp setup --revoke-sessions |
Signs every browser out, cancels unused sign-in links, and stops. |
email-mcp account add|list|reconnect|remove|test |
Manages accounts without a browser. reconnect <id> gives an account a new password or trusts its new certificate (the proof of identity that a server shows), and keeps the account. remove <id> asks first; add --yes without a terminal. See Manage accounts. |
email-mcp token create|list|revoke |
Manages the tokens (the secrets that an app sends to the local server) of local HTTP mode. create takes --expires-in and --in-band-confirm. See Local HTTP mode. |
email-mcp outbox list|cancel |
Lists the sends that wait to go out. cancel <id> stops one, at any permission level (a number from 0 to 5 that says what the agent may do with the mail of an account). See Activity and undo. |
email-mcp import-env [path] |
Imports the account of an old .env file (a text file of settings). See Moving from the old email-mcp. |
email-mcp key rotate --to file:<path>|keychain |
Changes the master key (the key that protects your stored passwords). See The master key. |
email-mcp doctor |
Checks the install. See Troubleshooting. |
email-mcp version |
Prints the version. |
email-mcp help |
Prints the list of commands. email-mcp -h and email-mcp --help do the same. |
Every command that opens the data takes --data-dir. email-mcp <command> -h
lists the flags of a command.
Flags
The table lists the flags that email-mcp <command> -h prints. The output of
-h writes each flag with one dash, such as -http. A flag works with one dash
or with two dashes. The table writes two dashes.
Every command in the table takes --data-dir, except help and version. It
names the data folder (the folder where email-mcp keeps its data). Without it,
email-mcp uses the folder in EMAIL_MCP_DATA_DIR, and then the folder of your
system. See Where the data lives. The flag
wins when both are set.
A password is never a flag, because other users of the computer can read the
flags of a running program. account add and account reconnect read the
password from standard input (the input of a program: what you type, or what a
pipe from another program gives it). The terminal asks for it, or, when
standard input is not a terminal, the first line of the input is the password.
An empty password for account reconnect keeps the stored one.
| Command | Flag | What it does |
|---|---|---|
serve |
--http <address> |
Serves MCP over local HTTP on this loopback address (an address that only your own computer can reach), such as 127.0.0.1:8765, instead of stdio. |
serve |
--allow-origin <origin> |
A browser origin (the address of a web page, such as http://localhost:5173) that may call the HTTP server. Repeat the flag for more. It needs --http. |
setup |
--revoke-sessions |
Signs every browser out, cancels unused sign-in links, and stops, without a new sign-in. |
account add |
--email <address> |
The email address of the account. Required. |
account add |
--imap-host <host> |
The IMAP (Internet Message Access Protocol: the protocol for reading mail) server, such as imap.example.com. Give both hosts, or neither to look them up. |
account add |
--smtp-host <host> |
The SMTP (Simple Mail Transfer Protocol: the protocol for sending mail) server, such as smtp.example.com. |
account add |
--imap-security <mode> |
The IMAP security: tls, starttls or plain. The default is tls. tls (Transport Layer Security) encrypts from the first byte. starttls starts plain and then switches encryption on. plain has no encryption. |
account add |
--smtp-security <mode> |
The SMTP security: tls, starttls or plain. The default is tls. |
account add |
--imap-port <number> |
The IMAP port (the number that names one service on an address). The default is 993 for tls, and 143 for starttls and plain. |
account add |
--smtp-port <number> |
The SMTP port. The default is 465 for tls, 587 for starttls, and 25 for plain. |
account add |
--username <name> |
The login name of both servers. The default is the email address. |
account add |
--plaintext-i-understand |
Allows a connection without encryption to a server on this computer. |
account add |
--trust-fingerprint <fingerprint> |
When standard input is not a terminal: trusts the certificate with this SHA-256 (Secure Hash Algorithm with 256 bits) fingerprint (a short code that identifies the certificate), if a server shows it in this run. Repeat the flag for the second server. |
account add |
--accept-remote-certificate |
When standard input is not a terminal: also needed to trust, with --trust-fingerprint, the certificate of a server that is not on this computer. |
account reconnect |
--trust-fingerprint <fingerprint> |
When standard input is not a terminal: accepts the certificate with this SHA-256 fingerprint, if a server shows it in this run. Repeat the flag for the second server. |
account reconnect |
--accept-remote-certificate |
When standard input is not a terminal: also needed to trust, with --trust-fingerprint, the certificate of a server that is not on this computer and had no trusted certificate. |
account reconnect |
--replace-pinned-certificate |
When standard input is not a terminal: also needed to replace, with --trust-fingerprint, the trusted certificate of a server whose certificate changed. |
account remove |
--yes |
Removes without a question. Needed when standard input is not a terminal. |
token create |
--name <name> |
A name for the token, such as the client that uses it. Required. |
token create |
--scopes <list> |
What the token allows, as a comma-separated list of email:read, email:organize, email:draft, email:send, email:delete (moves mail to the Trash), or all. Required. |
token create |
--expires-in <time> |
How long the token stays valid, such as 30d or 12h. The default is 90d, and the most is 3650d. |
token create |
--in-band-confirm |
Lets the app of this token answer a confirmation in its own window, instead of the approval page. Any program with the token can then answer for you. |
import-env |
--email <address> |
The email address of the account. The default is IMAP_USERNAME, when it is an address. |
import-env |
--plaintext-i-understand |
Allows IMAP_TLS=false or SMTP_TLS=false to a server on this computer. |
import-env |
--trust-fingerprint <fingerprint> |
When standard input is not a terminal: trusts the certificate with this SHA-256 fingerprint, if a server shows it in this run. Repeat the flag for the second server. |
import-env |
--accept-remote-certificate |
When standard input is not a terminal: also needed to trust, with --trust-fingerprint, the certificate of a server that is not on this computer. |
key rotate |
--to <key> |
The new master key: file:<absolute path> (a new file, made with mode 0600: only you can read and write it) or keychain (the password store of your operating system). |
key rotate |
--yes |
Rotates without a question. Needed when standard input is not a terminal. |
The commands account list, account test, token list, token revoke,
outbox list, outbox cancel and doctor have no flag except --data-dir.
version and help have no flag.