Imap Mini MCP

🚀 IMAP Mini MCP

A lightweight MCP (Model Context Protocol) server for reading IMAP email and creating draft replies. It works with any standard IMAP server and local bridges.

🚀 Quick Start

IMAP Mini MCP is a lightweight MCP server that enables reading IMAP emails and creating draft replies. It's compatible with standard IMAP servers like Gmail, Outlook, Fastmail, and local bridges such as ProtonMail Bridge. Agents can perform various operations on emails but cannot send or delete them.

✨ Features

• Email Operations: Agents can read, search, move, star, and organize emails, and compose drafts.
• Workflow Enhancement: It's recommended to use a speech - to - text tool and connect AI desktop applications to the MCP server for a faster workflow.
• Global Unique ID: Each email is identified by a composite ID that is globally unique and stable across folder moves.

📦 Installation

Agent configuration

Add the following to your MCP client config (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "imap-mini-mcp": {
      "command": "node",
      "args": ["/path/to/imap-mini-mcp/dist/index.js"],
      "env": {
        "IMAP_HOST": "imap.example.com",
        "IMAP_USER": "you@example.com",
        "IMAP_PASS": "your-password"
      }
    }
  }
}

The args path must point to the built dist/index.js. Add any optional variables to the env block as needed.

Environment variables

For most providers, just set the host, user, and password. For ProtonMail Bridge, all five settings below are required:

IMAP_HOST=127.0.0.1
IMAP_PORT=1143
IMAP_SECURE=false
IMAP_STARTTLS=false
IMAP_TLS_REJECT_UNAUTHORIZED=false

Or as MCP client config:

{
  "mcpServers": {
    "imap-mini-mcp": {
      "command": "node",
      "args": ["/path/to/imap-mini-mcp/dist/index.js"],
      "env": {
        "IMAP_HOST": "127.0.0.1",
        "IMAP_PORT": "1143",
        "IMAP_SECURE": "false",
        "IMAP_STARTTLS": "false",
        "IMAP_TLS_REJECT_UNAUTHORIZED": "false",
        "IMAP_USER": "you@proton.me",
        "IMAP_PASS": "your-bridge-password"
      }
    }
  }
}

💻 Usage Examples

Basic Usage

Use the find_emails tool to search and filter emails. All parameters are optional. Calling with no parameters returns all emails from INBOX, sorted newest - first.

// Example: Get emails from the last 24 hours
{
  "after": "24h"
}

Advanced Usage

You can use other tools to perform various operations on emails. For example, to create a draft reply from an existing email:

{
  "id": "YYYY-MM-DDTHH:mm:ss.<Message-ID>",
  "body": "Your reply content",
  "reply_all": true,
  "mailbox": "INBOX"
}

📚 Documentation

Tools

Every email is identified by a composite id (YYYY-MM-DDTHH:mm:ss.<Message-ID>). Use the id to perform operations on emails.

find_emails

Search and filter emails.

Examples:

Other tools

🔧 Technical Details

Troubleshooting

"IMAP connection closed unexpectedly" or "Server disconnected"

This usually means the server rejected the connection due to a TLS/STARTTLS mismatch. Verify these environment variables in your MCP client config:

"IMAP authentication failed"

Check that IMAP_USER and IMAP_PASS are correct. Some providers require an app - specific password.

"Cannot reach IMAP server — connection refused"

The IMAP server is not running or not listening on the configured host and port. For local bridges, make sure the bridge application is running.

Development

Build and run

npm install
npm run build

Local development with .env

Copy .env.example to .env and fill in your credentials, then:

npm start

When used through an MCP client, credentials are provided via the client config's env block.

Testing

Tests use vitest and mock the IMAP layer.

npm test             # run once
npm run test:watch   # watch mode
npm run lint         # type - check only

📄 License

MIT