Registry / communication / mcp-mail-server

mcp-mail-server

library1.2.1jsnpmunverified

An MCP (Model Context Protocol) server enabling AI assistants like Claude and Cursor to perform email operations via IMAP and SMTP. Current stable version is 1.2.1, maintained on GitHub with regular updates. Key differentiators: environment-based secure configuration, natural language commands for email tasks, automatic connection management, multi-mailbox support, attachment handling, and TLS/SSL compatibility. Designed for integration with AI agents that use the MCP protocol.

communication

npm install mcp-mail-server

github ↗package ↗

INSTALL

IMPORT

SIG · MCP-MAIL-SERVER

mcp-mail-server

communicationjavascriptv1.2.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MailServer

✓ import { MailServer } from 'mcp-mail-server'

✗ const MailServer = require('mcp-mail-server')

This package is an MCP server binary, not a library. It is executed as a command via npx.

Installs the MCP Mail Server globally and configures it as an MCP server for Claude Desktop with environment variables for IMAP and SMTP settings.

npm install -g mcp-mail-server # Then add to claude_desktop_config.json: { "mcpServers": { "mcp-mail-server": { "command": "npx", "args": ["-y", "mcp-mail-server"], "env": { "IMAP_HOST": "imap.example.com", "IMAP_PORT": "993", "IMAP_SECURE": "true", "SMTP_HOST": "smtp.example.com", "SMTP_PORT": "465", "SMTP_SECURE": "true", "EMAIL_USER": "user@example.com", "EMAIL_PASS": "replace-with-password" } } } }

Debug

Known issues

breakingSearch criteria (FROM/TO/SUBJECT/BODY/KEYWORD/SINCE) must use nested array format; previous single-array format causes errors.

fix

Update to version 1.2.1 or later, and ensure search criteria are provided as nested arrays.

affects: <1.2.1

breakingEmail dates are now stored in ISO 8601 format instead of locale string; existing email date parsing may break.

fix

Update to 1.2.1. If you rely on date strings, parse ISO 8601 instead of locale-specific strings.

affects: <1.2.1

gotchaEnvironment variables must be set exactly as documented. Missing IMAP_HOST or SMTP_HOST will cause connection failures.

fix

Ensure all required env vars are present: IMAP_HOST, IMAP_PORT, IMAP_SECURE, SMTP_HOST, SMTP_PORT, SMTP_SECURE, EMAIL_USER, EMAIL_PASS.

affects: all

deprecatedThe getRecentMessages() tool previously used the IMAP RECENT flag, which is unreliable. Now it fetches latest N messages by UID.

fix

Update to 1.2.1. The tool now behaves correctly; no code changes needed, but behavior differs.

affects: <1.2.1

gotchaThe reply_to_email tool may write literal "undefined" into the body when the text parameter is empty string.

fix

Update to 1.2.1. Ensure you always provide a non-empty text parameter.

affects: <1.2.1

gotchaEnsure IMAP_PORT and SMTP_PORT are strings, not numbers, when setting environment variables (e.g., '993' not 993).

fix

Use string values for ports in the env object.

affects: all

Errors

Common errors & fixes

Error: connect ECONNREFUSED your-imap-server.com:993

IMAP server is not reachable, or the hostname/port is incorrect.

fix

Verify IMAP_HOST and IMAP_PORT. Ensure the server allows connections from your network. If using TLS, IMAP_SECURE should be 'true' and port 993.

Error: Invalid search criteria: expected array of arrays

Search criteria not provided in the correct nested array format required by the IMAP library.

fix

Wrap each search condition in its own array. For example: [['FROM', 'someone@example.com'], ['SINCE', '01-Jan-2025']].

Error: getaddrinfo ENOTFOUND imap.example.com

The IMAP hostname cannot be resolved via DNS.

fix

Double-check the IMAP_HOST environment variable. Ensure the hostname is correct and accessible from your environment.

Error: No IMAP connection. Please ensure server is running.

The IMAP connection was not established before calling a tool that requires it.

fix

Verify that environment variables are set correctly and the IMAP server is reachable. Restart the MCP server.

Upgrade

Version history

1.2.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/yunfeizhu/mcp-mail-server ↗

packagehttps://www.npmjs.com/package/mcp-mail-server ↗