Skip to main content
Glama
email-mcp-server

email-mcp-server

by gaganmeena05

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

  1. 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.

  2. 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.

Exposed Tools

  • 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.

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 build

3. 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.js

This 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 tools
get_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

    A3.7/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLMs to read, search, and manage emails via IMAP with secure, read-only access to email accounts.
      6
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to read recent emails and fetch full email content from an IMAP inbox, allowing natural language queries about email summaries.
      3
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to read, search, and manage email via IMAP, and send emails with attachments via SMTP, using natural language commands.
      1,767 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to read, send, organize, and search emails across multiple IMAP/SMTP mailboxes.
      MIT