How to Connect an AI Assistant to Your Email With MCP
The short answer
Connect an AI assistant to your email by running an MCP server that handles your mail provider's OAuth flow, then adding it to your AI client's config. Once connected, the assistant can search, read, and draft emails as tool calls — but treat every email as untrusted input and keep sends approval-gated.
How to connect an AI assistant to your email with MCP: what tools get exposed, how OAuth scopes work, and what to do when it fails.
On this page
Most people who ask an AI to help with email are still working around the problem rather than through it. They paste a thread into a chat window, wait for the summary, copy the suggested reply, and paste it back into their inbox. It works, but it puts the human in the middle of every exchange — and the AI is operating on a static copy of the message, not the live mailbox.
The Model Context Protocol changes that arrangement. MCP is an open standard, maintained by Anthropic and adopted across AI clients including Claude, ChatGPT, Cursor, and VS Code Copilot, that lets an assistant connect to external tools and data sources through a defined interface. When a mail provider is wired up as an MCP server, the assistant does not need you to paste anything. It invokes tool calls directly: search for threads, pull the full text of a message, check attachment metadata, compose a draft — all against your live inbox. The workflow that used to require constant copy-and-paste becomes a single prompt.
This guide covers how to connect an AI assistant to your email with MCP end to end: the prerequisites, the step-by-step connection procedure, how the setup differs across AI clients, the most common failure modes and how to fix them, and the one security rule that cannot be skipped. By the end you will have a working connection and a clear picture of what the assistant can reach, what it cannot reach, and what requires your approval before it acts.
What you need before you start#
The connection has four parts that must align: an AI client that supports MCP, a mail provider that offers OAuth or IMAP access, an MCP server that bridges the two, and a config file that tells the client where the server lives. A gap in any one of them is the source of most setup failures, so it is worth confirming each before you touch a config file.
The table in the next section covers which AI clients support MCP and how their transport requirements differ. For the server itself: no official email MCP server exists in the MCP steering group's reference repository, which covers filesystem, Git, and similar tooling. Every email server available today is community-built. That is not a problem, but it means you should verify that whatever server you choose is actively maintained and documents which OAuth scopes it requests during the authorization step.
- An AI client that supports MCP as a host — Claude Desktop, ChatGPT (via a hosted server endpoint), Cursor, or VS Code with GitHub Copilot. A browser-based chat window without a desktop client cannot open a persistent connection to a local server process.
- A developer credential for your mail provider. Gmail requires an OAuth 2.0 client ID created in Google Cloud Console with the Desktop application type. Outlook requires an app registration in Azure Active Directory with the correct Microsoft Graph scopes. Providers that support IMAP — iCloud, Fastmail, Zoho, and most others — use an app-specific password rather than your account password.
- Node.js 18 or later installed locally if you plan to run a stdio-based server. Most community-built email MCP servers are Node.js packages installed via npm or npx.
- Your provider's credentials file or environment variable. For Gmail: a credentials.json downloaded from Google Cloud Console. Store it at a stable local path you reference in your config — never inside a folder that syncs to cloud storage or a version-controlled directory.
Community servers: check before you connect
How to connect an AI assistant to your email with MCP#
- 1
Pick a community-built email MCP server
Search the MCP Registry at registry.modelcontextprotocol.io or npm for a server that matches your mail provider. For Gmail, several actively maintained packages expose tools for searching, reading, drafting, and sending. For Outlook, look for servers built on the Microsoft Graph API. For IMAP providers, a generic IMAP server covers iCloud, Fastmail, Zoho, and most others. Before you install anything, check when the repository last received a commit, read the README for which scopes it will request, and confirm the token file stays local. A server that went unmaintained six months ago is a server you will be patching yourself when a provider changes its OAuth flow.
- 2
Create your provider credentials
For Gmail: open Google Cloud Console, create a project, enable the Gmail API, navigate to Credentials, and create an OAuth 2.0 client ID. Choose Desktop application as the type — a web application client ID will not work with a local stdio server. Download the credentials.json file and place it at a path you will reference in your config, such as ~/.config/gmail-mcp/credentials.json. For Outlook: go to Azure Active Directory in the Azure portal, register a new application, record the client ID and tenant ID, and add the Microsoft Graph Mail.Read permission — add Mail.ReadWrite if you want draft support. For IMAP providers: generate an app-specific password in your provider's security settings and store it in an environment variable rather than pasting it directly into a config file.
- 3
Run the server once to complete the OAuth flow
Start the server from your terminal using npm or npx with the path to your credentials file. The server opens a browser tab pointing to your mail provider's authorization consent screen. Before you click Allow, read the list of requested permissions carefully — this is the moment to verify that the server is requesting only what it documented. For a read-only setup, decline any send or delete scope and check whether the server starts correctly with reduced permissions. After you grant access, the server writes a token file locally. Subsequent launches read the token without opening a browser. If the token ever expires or is revoked, delete the token file and run this step again.
- 4
Add the server to your AI client configuration file
Open your client's MCP configuration file. For Claude Desktop on macOS the path is ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows it is in %APPDATA%/Claude/. Add a key under mcpServers with the server command, any arguments, and any environment variables the server needs — typically the path to credentials.json and the path where the token should be stored. Save the file. For ChatGPT and other browser-based clients that require Streamable HTTP transport rather than stdio, you will need to deploy the server to a publicly reachable HTTPS endpoint first; a server running on localhost is not reachable from the browser-based client. Cursor and VS Code follow the same JSON structure as Claude Desktop, with the config file in the respective IDE settings directory.
- 5
Restart the client and verify the tools are live
Quit the AI client completely and reopen it. In Claude Desktop, look for the tool icon in the chat input area — clicking it shows which tools are currently available from connected servers. If your email server's tools appear in that list, send a low-stakes test prompt: ask the assistant to find an email you sent yourself in the last few days. A result with the correct subject line and sender confirms the connection is working. If nothing comes back or you see a connection error, jump to the troubleshooting section before running anything else.
Platform differences: Claude, ChatGPT, Cursor, and VS Code#
The connection process is the same in principle across AI clients — run a server, point the client at it, restart — but the transport type the client supports changes the practical setup significantly. Clients that support local stdio servers can connect to a process running on your own machine. Clients that require Streamable HTTP need the server hosted at a reachable URL, which adds a deployment step.
If you are starting out, Claude Desktop with a local stdio server is the path with the most community documentation and the fewest moving parts. The ChatGPT path is viable but requires hosting infrastructure that most guides skip. Cursor is a strong choice when your email workflow overlaps with code — reviewing error reports in threads, checking release-note context while writing — because the same MCP config powers both.
| AI client | Transport supported | Config location | Notes |
|---|---|---|---|
| Claude Desktop | stdio (local) and Streamable HTTP | claude_desktop_config.json in the Claude app support directory | Most community email MCP guides target this client; the most straightforward starting point |
| ChatGPT | Streamable HTTP only | ChatGPT settings panel under Connected tools | Requires the server deployed at a publicly reachable HTTPS endpoint; a local stdio server running on localhost does not work from the browser client |
| Cursor | stdio and Streamable HTTP | .cursor/mcp.json in the project directory or user-level Cursor settings | Same JSON config structure as Claude Desktop; useful for engineering workflows that include email context |
| VS Code (GitHub Copilot) | stdio and Streamable HTTP | .vscode/mcp.json or user settings.json under mcp.servers | Supported with GitHub Copilot enabled; check the VS Code release notes for the minimum version that added MCP support in your channel |
What to do when the connection fails#
Most MCP email setup failures trace to one of five causes: a malformed config file, a credential problem, a scope mismatch between what the server needs and what you authorized, a runtime version issue, or an expired token. None of these require deep debugging — each one leaves a recognizable trace in the server's terminal output or the client's error log.
One apparent failure that is not a failure: if you prompt the assistant to act on instructions it found inside an email — forward to a new address, retrieve content from a link in the message, change its own behavior based on text in a thread — and it refuses or asks you to confirm, that is correct behavior. A properly built MCP server treats incoming email content as untrusted data, not as commands to execute. That refusal is the system working. Do not configure the server to trust email content as instructions.
| Symptom | Likely cause | Fix |
|---|---|---|
| Tools don't appear after restarting the client | JSON syntax error in the config file, or the server process failed to start | Run the server command manually in your terminal to see startup errors; paste the config file into a JSON validator to catch syntax mistakes |
| OAuth error: invalid_client | The credentials.json path in your config is wrong, or you created a web application client ID instead of a desktop one | Verify the exact file path; if needed, delete the credential and regenerate it in Google Cloud Console with Desktop application selected as the type |
| Tool runs but returns no results | The scopes you granted at authorization are too narrow for what the server is trying to do | Delete the token file, restart the server to re-run the OAuth flow, and grant the scopes the server requests at the consent screen |
| Server process exits immediately | Node.js version below 18, or a missing npm dependency | Run node --version in your terminal; upgrade Node.js if needed; run npm install in the server directory before restarting |
| Connection drops after a few hours | The OAuth token expired and the server is not refreshing it automatically | Check whether the server has a refresh token; some servers need the offline_access scope included at authorization to keep the session alive; delete the token file and re-authorize if needed |
Email content is untrusted input — this is non-negotiable
A faster way to connect AI to your mailbox#
The steps above work. Once the connection is running, the assistant can search, read, and triage threads without you copying anything, and that is genuinely useful. The operational cost is in the ongoing maintenance: credentials that need refreshing, token files to track, config updates when the server ships a breaking change, and a new OAuth consent round each time you add a second provider. That overhead grows with each inbox you connect.
AI Emaily is an AI-native email client built around direct mailbox integration — Gmail, Outlook, and IMAP providers all connect through the same OAuth flow, handled inside the app. No server process to keep alive, no config file to edit when something changes, no token file stored in a folder you have to remember. The agent reads, drafts, and triages inside a client built for the purpose, with an audit log of every action it takes, an undo window on sends, and approval-gating in Copilot mode before anything leaves your outbox. We build AI Emaily. If you want the assistant-plus-mailbox setup without the MCP plumbing, it is worth a look at aiemaily.com/mcp.
Frequently asked
See it in AI Emaily
Keep reading
Sources
Written by
Nafiul HasanNafiul Hasan is an entrepreneur and AI automation system builder with 10+ years of experience turning messy, manual workflows into reliable automated systems. He designs and ships AI enterprise solutions end-to-end — the agent logic, the data plumbing, and the product people actually use — and founded AI Emaily to give busy professionals their attention back. He writes here from the builder's seat: what works, what breaks, and how to put AI to work without giving up control.