email-mcp-server
Provides tools to list recent emails, read full email content, and summarize messages from a Gmail inbox via IMAP.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@email-mcp-server What are the last few emails from my boss?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Email MCP Server
This project is a custom Model Context Protocol (MCP) server built to allow AI Assistants (like Claude, Cursor, or custom agents) to dynamically read and interact with a user's email inbox.
It was built as a learning project to understand the MCP architecture and integrate legacy protocols (IMAP) with modern AI tools.
What is MCP?
The Model Context Protocol (MCP) is an open standard that allows AI models to securely access external tools and data sources. Instead of hardcoding API integrations into an AI client, the AI connects to an "MCP Server" which exposes a standardized set of Tools and Resources.
Related MCP server: Email MCP Server
Architecture & Tech Stack
This server is built using:
Node.js & TypeScript: For type-safe backend logic.
@modelcontextprotocol/sdk: The official SDK for creating MCP servers.
imap-simple & mailparser: For connecting to email providers via the standard IMAP protocol and parsing raw email bodies.
dotenv: For secure credential management.
Component Breakdown
The MCP Server (
src/index.ts)We initialize an MCP
Serverinstance and configure it to use stdio (Standard I/O) transport. This is the standard way local MCP servers communicate securely with AI clients—they pass JSON-RPC messages back and forth through terminal input/output rather than opening web ports.We register a
ListToolsRequestSchemahandler to tell the AI what tools are available.We register a
CallToolRequestSchemahandler to actually execute the logic when the AI decides to use a tool.
The Data Layer (
src/emailClient.ts)This module isolates the IMAP logic.
Optimization Note: Initially, querying an inbox with thousands of emails using
['ALL']caused severe timeouts. To optimize this, the code was refactored to first get thetotalmessage count from the inbox, calculate the starting sequence number (e.g.,total - limit), and use IMAP Sequence Ranges (e.g.,91:*). This ensures we only download the headers for the exact number of recent emails requested, making the tool lightning fast.
Exposed Tools
list_recent_emails: Connects to the inbox and fetches the sender, subject, and ID of theNmost recent emails.read_email: Takes a specific email ID and fetches the full parsed text body.summarize_email: An internal mock tool demonstrating how server-side processing could work.
How to Run & Test
1. Setup Credentials
Create a .env file in the root directory:
EMAIL_ADDRESS=your_email@gmail.com
APP_PASSWORD=your_16_digit_app_password(Note: For Gmail, you must generate an App Password in your Google Account Security settings. Do not include spaces in the password).
2. Build the Server
npm install
npm run build3. Testing with MCP Inspector
The easiest way to test the server in isolation (without an AI client) is using the official MCP Inspector:
npx @modelcontextprotocol/inspector node build/index.jsThis boots up a proxy server. Cmd/Ctrl + Click the URL printed in the terminal to open the web UI, click "Connect", and you can manually trigger the tools.
4. Connecting to Claude Desktop
To let Claude read your emails, add this server to your claude_desktop_config.json:
"mcpServers": {
"email-server": {
"command": "node",
"args": [
"/absolute/path/to/email-mcp-server/build/index.js"
],
"env": {
"EMAIL_ADDRESS": "your_email@gmail.com",
"APP_PASSWORD": "your_16_digit_app_password"
}
}
}Restart Claude, and you can now ask it: "Can you check my recent emails and summarize any important updates from my boss?"
Available Tools
8 toolsget_unread_emailsB
Fetch a list of recent UNREAD emails.
Inputs: limit.
list_recent_emailsB
List the most recent emails in the inbox.
Inputs: limit.
mark_as_readB
Mark an email as read in the inbox.
Inputs: id (required).
read_emailA
Read the full body content of a specific email by ID.
Inputs: id (required).
reply_to_emailA
Reply to an existing email thread using its original ID.
Inputs: body (required), original_email_id (required).
search_emailsA
Search for emails matching a query in the sender or subject.
Inputs: query (required), limit.
send_emailB
Send a brand new email to an address.
Inputs: to (required), body (required), subject (required).
summarize_emailA
Get an AI summary of a specific email by ID.
Inputs: id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Tools mostly have distinct purposes, but get_unread_emails and list_recent_emails both list emails (with different filters), and read_email vs summarize_email both fetch a specific email. Descriptions clarify the differences, so confusion is unlikely.
All tools follow a consistent verb_noun pattern in snake_case (e.g., get_unread_emails, mark_as_read, send_email). Minor modifiers like 'unread' or 'recent' do not break the convention.
8 tools is well within the ideal 3-15 range and covers a balanced set of email operations without unnecessary bloat. Each tool has a clear purpose.
Core email workflows (list, read, search, send, reply, mark read) are covered. Missing operations like delete, archive, or attachment handling are minor gaps that agents can work around for most use cases.
Maintenance
Related MCP Connectors
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.
Your mailboxes in ChatGPT and Claude: Gmail, iCloud, Fastmail, any IMAP. Passwords stay yours.
Give AI agents their own email inboxes: list, read and send mail via scoped, revocable OAuth grants.
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to read, search, and manage emails via IMAP with secure, read-only access to email accounts.6MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to read recent emails and fetch full email content from an IMAP inbox, allowing natural language queries about email summaries.3ISC
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to read, search, and manage email via IMAP, and send emails with attachments via SMTP, using natural language commands.1,767 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to read, send, organize, and search emails across multiple IMAP/SMTP mailboxes.MIT