User manual
email-mcp gives an AI (artificial intelligence) agent access to your email. The
agent is the AI program that uses the tools of email-mcp. A tool is one action
that the agent can call, such as search_messages. email-mcp is an MCP server.
MCP (Model Context Protocol) is an open standard that lets AI apps, such as
Claude Code, call tools that other programs offer.
- It works with mail providers that offer IMAP (Internet Message Access Protocol: the protocol for reading mail) and SMTP (Simple Mail Transfer Protocol: the protocol for sending mail), with a password or an app password. An app password is a separate password that you make in your mail account for one program. See App passwords. Some tools need features of the mail server. See What the mail server needs.
- It runs on your own computer. Your passwords stay on your computer, encrypted.
- You decide what the agent may do, per account: only read, also organize, also write drafts, also send, also move mail to the Trash. Each choice is a level: a number from 0 (no access) to 5 (also move mail to the Trash).
- By default, every send waits for your “yes”. Moving mail to the Trash needs
level 5. Mail servers differ, so email-mcp may not recognize every Trash
folder. At level 5, a move to the Trash waits for your “yes” too. The
exceptions are drafts. At level 3
discard_draftmoves a draft to the Trash without a question. When the agent sends a saved draft (send_messagewithdraft_ref, the reference of the draft), email-mcp moves that draft to the Trash after the mail server takes the message (level 4 is enough). Neither counts toward the daily Trash limit (the most messages that the agent may move to the Trash in one day). - One server can hold several accounts.
How the parts fit
email-mcp has three parts that work together. The AI app starts email-mcp. email-mcp talks to your mail server. You use the web pages of email-mcp in your browser. The web pages are pages that email-mcp shows on your own computer.
What you need
- A mail account at a provider (the company that runs your mail) that offers IMAP and SMTP, with a password or an app password.
- A terminal (a window where you type commands). You paste a few commands into it.
- An AI app that can use MCP servers, such as Claude Code.
The way in
Read these four pages in order. After them, you have a working setup.
- Install email-mcp puts the program on your computer and checks that it runs.
- Connect your first account connects one mail account, in the browser or without a browser.
- Connect an AI app adds email-mcp to Claude Code, Claude Desktop, Cursor, VS Code or the Codex CLI.
- Your first use checks the install, asks a first question, and shows what to expect when the agent wants to send.
Find your task
- I want to install email-mcp.
- I want to update email-mcp to a new version.
- I want to connect a mail account.
- I want to connect a second account.
- I want to connect an AI app.
- I want to let the agent send mail.
- I want to answer a send that waits for me.
- I want to turn off the access of the agent to an account (level 0).
- I want to cancel a send.
- I want to see what the agent did.
- I want to fix a failed login.
- I want to use an AI app that cannot start a program.
- I want to check a download.
What is not in this version
This version covers mail only. Calendar and contacts, sign-in with Google or Microsoft (OAuth: a way to sign in without giving a program your password), and a hosted mode for many people (one server that many people use) are planned. They are not available. Until then, connect Google and Microsoft accounts with an app password.
email-mcp uses the MIT license. See LICENSE on GitHub.