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_draft moves a draft to the Trash without a question. When the agent sends a saved draft (send_message with draft_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.

The three parts of email-mcp The AI app starts email-mcp. email-mcp talks to your mail server. You use the web pages of email-mcp in your browser. AI app email-mcp Mail server starts talks to uses the web pages You

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.

  1. Install email-mcp puts the program on your computer and checks that it runs.
  2. Connect your first account connects one mail account, in the browser or without a browser.
  3. Connect an AI app adds email-mcp to Claude Code, Claude Desktop, Cursor, VS Code or the Codex CLI.
  4. Your first use checks the install, asks a first question, and shows what to expect when the agent wants to send.

Find your task

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.