{"id":27141,"library":"mcp-mail-server","title":"MCP Mail Server","description":"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.","status":"active","version":"1.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/yunfeizhu/mcp-mail-server","tags":["javascript","mcp","imap","smtp","email","mail","server","cursor","claude"],"install":[{"cmd":"npm install mcp-mail-server","lang":"bash","label":"npm"},{"cmd":"yarn add mcp-mail-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add mcp-mail-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is an MCP server binary, not a library. It is executed as a command via npx.","wrong":"const MailServer = require('mcp-mail-server')","symbol":"MailServer","correct":"import { MailServer } from 'mcp-mail-server'"}],"quickstart":{"code":"npm install -g mcp-mail-server\n# Then add to claude_desktop_config.json:\n{\n  \"mcpServers\": {\n    \"mcp-mail-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-mail-server\"],\n      \"env\": {\n        \"IMAP_HOST\": \"imap.example.com\",\n        \"IMAP_PORT\": \"993\",\n        \"IMAP_SECURE\": \"true\",\n        \"SMTP_HOST\": \"smtp.example.com\",\n        \"SMTP_PORT\": \"465\",\n        \"SMTP_SECURE\": \"true\",\n        \"EMAIL_USER\": \"user@example.com\",\n        \"EMAIL_PASS\": \"replace-with-password\"\n      }\n    }\n  }\n}","lang":"json","description":"Installs the MCP Mail Server globally and configures it as an MCP server for Claude Desktop with environment variables for IMAP and SMTP settings."},"warnings":[{"fix":"Update to version 1.2.1 or later, and ensure search criteria are provided as nested arrays.","message":"Search criteria (FROM/TO/SUBJECT/BODY/KEYWORD/SINCE) must use nested array format; previous single-array format causes errors.","severity":"breaking","affected_versions":"<1.2.1"},{"fix":"Update to 1.2.1. If you rely on date strings, parse ISO 8601 instead of locale-specific strings.","message":"Email dates are now stored in ISO 8601 format instead of locale string; existing email date parsing may break.","severity":"breaking","affected_versions":"<1.2.1"},{"fix":"Ensure all required env vars are present: IMAP_HOST, IMAP_PORT, IMAP_SECURE, SMTP_HOST, SMTP_PORT, SMTP_SECURE, EMAIL_USER, EMAIL_PASS.","message":"Environment variables must be set exactly as documented. Missing IMAP_HOST or SMTP_HOST will cause connection failures.","severity":"gotcha","affected_versions":"all"},{"fix":"Update to 1.2.1. The tool now behaves correctly; no code changes needed, but behavior differs.","message":"The getRecentMessages() tool previously used the IMAP RECENT flag, which is unreliable. Now it fetches latest N messages by UID.","severity":"deprecated","affected_versions":"<1.2.1"},{"fix":"Update to 1.2.1. Ensure you always provide a non-empty text parameter.","message":"The reply_to_email tool may write literal \"undefined\" into the body when the text parameter is empty string.","severity":"gotcha","affected_versions":"<1.2.1"},{"fix":"Use string values for ports in the env object.","message":"Ensure IMAP_PORT and SMTP_PORT are strings, not numbers, when setting environment variables (e.g., '993' not 993).","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"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.","cause":"IMAP server is not reachable, or the hostname/port is incorrect.","error":"Error: connect ECONNREFUSED your-imap-server.com:993"},{"fix":"Wrap each search condition in its own array. For example: [['FROM', 'someone@example.com'], ['SINCE', '01-Jan-2025']].","cause":"Search criteria not provided in the correct nested array format required by the IMAP library.","error":"Error: Invalid search criteria: expected array of arrays"},{"fix":"Double-check the IMAP_HOST environment variable. Ensure the hostname is correct and accessible from your environment.","cause":"The IMAP hostname cannot be resolved via DNS.","error":"Error: getaddrinfo ENOTFOUND imap.example.com"},{"fix":"Verify that environment variables are set correctly and the IMAP server is reachable. Restart the MCP server.","cause":"The IMAP connection was not established before calling a tool that requires it.","error":"Error: No IMAP connection. Please ensure server is running."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}