Allows AI assistants to read and interact with a user's Gmail inbox, including listing recent emails and reading full email bodies via IMAP.
Click on "Install 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 list my 5 most recent emails"
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?"
List the most recent emails in the inbox (without bodies).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of emails to return (default 5) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool returns only recent emails without bodies, implying a read-only, non-destructive operation. However, since no annotations are provided, it does not explicitly state its side-effect free nature, required authentication, or the exact sorting criteria. This is adequate but could be more explicit.
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 that front-loads the core purpose. Every word is meaningful, with no redundancy or filler.
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 does not specify what fields are returned in the email list (e.g., subject, sender, timestamp), nor does it mention any pagination or handling of large result sets. Given the lack of an output schema, the description should provide more detail on the response format to be fully 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 already provides a description for the only parameter 'limit' (default 5). The tool description adds no additional semantic value beyond what the schema offers, so it meets the baseline of 3.
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'), the resource ('most recent emails'), and the scope ('inbox'), while also specifying what is excluded ('without bodies'). This distinguishes it from sibling tools 'read_email' (which likely includes bodies) and 'summarize_email' (which would provide a summary).
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 that if bodies are needed, one should use 'read_email' instead, but it does not explicitly state when to use this tool versus its siblings. No direct guidance on prerequisites or alternatives is provided beyond the implication from the 'without bodies' qualifier.
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 provided, so the description carries full burden. It states it is a read operation, which is non-destructive, but lacks details on permissions, rate limits, 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?
Single sentence, to the point, no 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?
For a simple read tool with one parameter and no output schema, the description is adequate, though it could mention authentication or return format.
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%, so the description adds minimal value beyond the schema's parameter description. The phrase 'full body content' describes the operation, not the parameter.
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 verb 'read', the resource 'email by ID', and specifies 'full body content', distinguishing it from sibling tools 'list_recent_emails' and 'summarize_email'.
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 the full body of a specific email is needed, but does not explicitly state when not to use it or mention alternatives.
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 (Internal Server-Side Summarization Demo).
| 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?
No annotations are provided, so the description carries the burden. It adds that it is an 'AI summary' and a 'Demo', but does not disclose behavioral traits such as idempotency, rate limits, error handling, or whether it requires authentication beyond what is assumed.
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 unnecessary words. The parenthetical 'Internal Server-Side Summarization Demo' is slightly extraneous but does not detract significantly. It is appropriately front-loaded.
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?
Given a single parameter and no output schema, the description explains the input and action. However, it does not mention how to obtain the email ID or what the output format is, which would be helpful given the sibling tools. 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?
Schema coverage is 100% with a clear description for 'id'. The description adds 'by ID' but no further semantics. Baseline 3 is appropriate as the schema already documents the parameter adequately.
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 verb 'Get', the resource 'AI summary of a specific email', and the method 'by ID'. It distinguishes from siblings: list_recent_emails lists emails, read_email reads full content, while this provides a summary.
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 obtaining a summary rather than the full email or list, but does not explicitly state when to use or when not to use, nor does it mention prerequisites like fetching the email ID first.
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. Dates show when Glama detected each change.
v1.0.0list_recent_emailsread_emailsummarize_emailEach tool serves a distinct purpose: listing emails, reading full content, and summarizing. No overlap in functionality, making it easy for an agent to select the correct tool.
All tools follow a consistent verb_noun pattern with snake_case naming (list_recent_emails, read_email, summarize_email), providing clear and predictable naming.
With only 3 tools, the server is on the thin side but acceptable for a focused demo or specialized task. However, it may feel insufficient for broader email management.
The server lacks essential email operations like sending, deleting, or searching, limiting its usefulness. It only covers reading and summarizing, leaving significant gaps for typical email workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Rajath2000/email-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
