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.
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.
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: IMAP Email MCP Server
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.
The MCP Server (src/index.ts)
We initialize an MCP Server instance 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 ListToolsRequestSchema handler to tell the AI what tools are available.
We register a CallToolRequestSchema handler 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 the total message 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.
list_recent_emails: Connects to the inbox and fetches the sender, subject, and ID of the N most 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.
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).
npm install
npm run buildThe 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.
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?"
Fetch a list of recent UNREAD emails.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of emails to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Fetch' which implies a read operation, but it does not clarify whether fetching unread emails triggers any side effects (e.g., automatically marking them as read). It also leaves 'recent' undefined and does not describe ordering or pagination behavior, leaving significant ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler. It is efficiently structured and immediately communicates the core functionality with minimal words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is minimally adequate: it conveys the overall purpose and return type. However, it omits details about 'recent' (time range), default behavior of 'limit', and whether the operation is read-only, leaving gaps that matter for an AI agent invoking it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for the single 'limit' parameter with the description 'Maximum number of emails to return'. The tool description adds no additional meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and identifies the resource ('list of recent UNREAD emails'), which clearly distinguishes it from sibling tools like 'list_recent_emails' (which may not filter by unread) and 'read_email' (which fetches a single email). The focus on 'UNREAD' provides a specific scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'search_emails' or 'list_recent_emails'. The description does not mention any conditions, exclusions, or context that would help an agent choose this tool over its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the most recent emails in the inbox.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of emails to return (default 10) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does not state whether the operation is read-only, how 'recent' is defined, what fields are returned, or any side effects. This is minimal information for a tool interaction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential action and target without unnecessary words. It is appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no output schema, the description provides the basic purpose but leaves gaps: it does not explain what 'recent' means, whether it includes unread or all emails, or the return format. This makes it adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the sole parameter 'limit' with a description, achieving 100% schema description coverage. The tool description adds no additional parameter semantics, so it stays at the baseline of 3 as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the target ('the most recent emails in the inbox'), making the core purpose unambiguous. It does not explicitly distinguish from sibling tools like get_unread_emails or search_emails, but the scope is specific enough to infer a distinct function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool instead of alternatives. It does not mention exclusions or relationships to siblings such as get_unread_emails or search_emails, leaving the agent to guess the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark an email as read in the inbox.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the email to mark as read |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states the action and location ('inbox'), leaving unspecified side effects, return value, authentication requirements, or error conditions. Since no annotations are provided, this minimal statement does not disclose whether the operation is reversible or if it triggers notifications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words, clearly front-loading the verb and object. It is appropriately sized and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple, the description lacks guidance on how the ID is obtained, what the tool returns, and how it relates to sibling tools. The absence of annotations and output schema increases the need for behavioral and usage context, which is not provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is fully described in the schema ('The ID of the email to mark as read'), so the description adds no additional parameter context. Baseline 3 applies due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'mark' and names the resource 'an email', making the action distinct from sibling tools like read_email (which retrieves content) or get_unread_emails (which lists). It clearly states the primary function and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. It simply states the action without indicating prerequisites, typical use cases, or exclusions, leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the full body content of a specific email by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the email to read |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It does not mention potential side effects (e.g., marking as read), authentication requirements, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded, concise sentence that clearly conveys the tool's function without any unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately conveys the main return value (full body) despite the lack of an output schema. It misses minor details like body format (plain vs HTML) and whether reading alters read status, but for a simple tool it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the single 'id' parameter with 100% coverage. The description adds no extra meaning beyond 'by ID', which is redundant with the schema's field description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the full body content of a specific email by ID. This distinguishes it from sibling tools like list_recent_emails (which lists) and mark_as_read (which mutates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have an email ID and need its full contents, but does not explicitly contrast with alternatives like get_unread_emails or search_emails. No exclusions or when-not guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reply to an existing email thread using its original ID.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The text of your reply | |
| original_email_id | Yes | The ID of the email to reply to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention any side effects (e.g., sending the reply, modifying the thread), permissions required, potential errors, or rate limits. For a mutation tool, this is a noticeable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's core purpose. Every word contributes meaning, with no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, with a fully documented schema and no output schema needed. The description, while brief, covers the essential input requirement (original email ID) and the action. Given the low complexity, this is reasonably complete, though it could benefit from a note about expected behavior or usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameters with clear descriptions. The tool description does not add significant meaning beyond the schema, merely restating the 'original ID' concept. Baseline 3 is appropriate since the schema already documents the parameters well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: replying to an existing email thread using its original ID. It distinguishes itself from siblings like send_email (which sends new emails) and read_email (which retrieves content). The verb+resource structure is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when the user wants to reply to an existing thread, as opposed to creating a new email. However, it does not explicitly mention when not to use it or provide alternatives, leaving the usage context implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for emails matching a query in the sender or subject.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of emails to return | |
| query | Yes | The text to search for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the search scope (sender or subject) but does not detail return format, ordering, pagination, case sensitivity, or whether it searches other fields like body or attachments.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct and front-loaded with the primary action and scope. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with two parameters and no output schema, the description is adequate but incomplete. It lacks details on return values, sorting, and search behavior, leaving gaps that require the agent to infer from sibling tools or context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters described. The description adds meaningful context by specifying that the query searches only the sender or subject field, clarifying the query parameter's intended use beyond the generic schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches for emails by query in the sender or subject, providing a specific verb ('search'), resource ('emails'), and scope that distinguishes it from sibling tools like list_recent_emails and get_unread_emails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding specific emails by query but does not explicitly discuss alternatives or when-not-to-use scenarios. The limitation to sender/subject is implied guidance but no exclusions or sibling comparisons are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a brand new email to an address.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | The recipient email address | |
| body | Yes | The plaintext body of the email | |
| subject | Yes | The subject line |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, but it only states the action and does not mention side effects, prerequisites (e.g., authentication), delivery guarantees, or what happens on failure. The word 'brand new' hints at intent but does not disclose operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundancy. Every word contributes to conveying the core function, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three required parameters and no output schema, the description is minimally adequate but omits useful context such as typical use cases, relation to reply_to_email, or expected outcome. It falls short of being fully self-contained but is not severely incomplete for a simple action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minimal meaning beyond the schema, only reinforcing that the email is sent 'to an address.' It does not clarify formats, constraints, or relationships between parameters beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Send a brand new email to an address' uses a specific verb (send) and resource (email), and the phrase 'brand new' clearly distinguishes it from sibling tools like reply_to_email, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as reply_to_email or search_emails. The description only states what it does, with no context on appropriate usage scenarios or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an AI summary of a specific email by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the email to summarize |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states the core action and does not mention side effects (e.g., whether the email is marked as read), return format, or behavior when the ID is invalid. This is a gap for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded with the core action and includes the necessary parameter reference.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, no output schema), but the description is thin. It does not state what the summary contains, its format, or any error behavior. While adequate for a minimal tool, it leaves out details that would help an agent understand the output and edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter 'id' with a clear description. The tool description adds no extra meaning beyond 'by ID,' but since schema coverage is 100%, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get an AI summary of a specific email by ID.' The verb 'get' and resource 'summary' are specific, and it is easily distinguished from sibling tools like read_email (full content) and mark_as_read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a summary is desired rather than full email content, but it does not explicitly state when not to use it or mention alternatives like read_email. The context is clear but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_unread_emailslist_recent_emailsmark_as_readread_emailreply_to_emailsearch_emailssend_emailsummarize_emailScored 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.
Connect any mailbox to Claude, ChatGPT & AI: read, send, reply, schedule & search emails.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Stateful email for AI agents — read inboxes, reply in-thread, draft with approval.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
