yunfeizhu/mcp-mail-server

45 stars 0 forks 품질 90 트렌드 90

Search, read, organize, reply to, and send email through supported password- or app-password-based IMAP/SMTP accounts—from Claude, Cursor, Codex, and other MCP clients.

개요

Search, read, organize, reply to, and send email through supported password- or app-password-based IMAP/SMTP accounts—from Claude, Cursor, Codex, and other MCP clients.

README

“Find the unread messages from Alice this week, summarize them, and move the finished thread to Archive.”

Why this server?

What can I ask?

Goal	Example prompt
Catch up	“Summarize my unread email from today.”
Find a message	“Find messages from [email protected] about the Q3 budget.”
Organize the inbox	“Move the completed thread from INBOX to Archive.”
Reply with context	“Reply to the latest message from Alex and keep it in the same thread.”
Handle files	“Save the PDF attachment from that message to my Downloads folder.”
Send polished email	“Send the project update with my text and HTML signature.”

Quick Start

[!IMPORTANT] Enable IMAP and SMTP for your account before starting. This server currently supports password or app-password authentication; OAuth2 is not yet supported.

Prepare your IMAP/SMTP server details and an app password where supported.
Add the server to your MCP client using one of the configurations below.
Restart or reconnect the client, then ask: “Show me unread emails from today.”

All examples use npx -y mcp-mail-server, so there is nothing to install globally.

Client setup

Tools at a glance

Capability	Tools
Connection	`check_connection`
Mailboxes	`list_mailboxes`
Search	`search_messages`, `find_unreplied_messages`
Messages	`get_message`, `get_messages`, `move_message`, `delete_message`
Compose	`send_email`, `reply_to_email`, `continue_email_thread`
Attachments	Attachment metadata in `get_message`, files through `save_attachment`

Configuration

Environment Variables

Core mail variables are required. File and security policy variables are optional.

Variable	Description	Example
`IMAP_HOST`	IMAP server address	`imap.gmail.com`
`IMAP_PORT`	IMAP port number, 1-65535	`993`
`IMAP_SECURE`	Must be `true`; use an implicit TLS IMAP endpoint, normally port 993	`true`
`SMTP_HOST`	SMTP server address	`smtp.gmail.com`
`SMTP_PORT`	SMTP port number, 1-65535	`465`
`SMTP_SECURE`	Use implicit TLS on port 465; set `false` on port 587 to require STARTTLS before authentication	`true`
`EMAIL_USER`	Email username	`[email protected]`
`EMAIL_PASS`	Email password/app password	`your-app-password`
`EMAIL_ADDRESS`	Outgoing From address and reply-all account identity; defaults to `EMAIL_USER`	`[email protected]`
`IMAP_TLS_REJECT_UNAUTHORIZED`	Verify the IMAP TLS certificate; defaults to `true`	`true`
`SMTP_TLS_REJECT_UNAUTHORIZED`	Verify the SMTP TLS certificate; defaults to `true`	`true`
`MAIL_ALLOWED_ROOTS`	Existing attachment read/write roots. Local attachment access is disabled when unset. Separate roots with `:` on macOS/Linux or `;` on Windows	`/Users/me/Documents:/tmp/mail`
`MAIL_MAX_ATTACHMENT_BYTES`	Per-attachment and total attachment limit; defaults to 25 MiB, maximum 1 GiB	`26214400`
`MAIL_MAX_MESSAGE_BYTES`	Maximum bytes parsed in memory for one message; defaults to 25 MiB, maximum 1 GiB	`26214400`
`MAIL_MAX_BASE64_BYTES`	Maximum attachment size returned as Base64; defaults to 1 MiB, maximum 100 MiB	`1048576`
`MAIL_MAX_BODY_CHARACTERS`	Maximum returned characters for each text or HTML body; defaults to 200000, maximum 10000000	`200000`
`MAIL_MAX_RESPONSE_CHARACTERS`	Maximum combined text and HTML characters returned by one body-reading tool call; defaults to 2000000, maximum 100000000	`2000000`
`MAIL_MAX_SEARCH_CANDIDATES`	Maximum message headers inspected across one search or reply-state tool call; defaults to 5000, maximum 100000	`5000`
`MAIL_MAX_SEARCH_HEADER_BYTES`	Maximum raw requested-header bytes buffered across one search or reply-state tool call; defaults to 16 MiB, maximum 1 GiB	`16777216`

Search results include sourceMailbox, uid, and uidValidity. Pass these values back unchanged when reading, replying, moving, downloading attachments, or deleting so identical UIDs in different mailboxes cannot resolve to the wrong message. Unstable IMAP sequence numbers are not exposed as message IDs. size is the server-provided RFC822 byte size and is null when the server omits it. Search returns summaries by default; use get_message for full bodies and attachment metadata, or set includeBody: true explicitly.

Common Email Providers

Security Notes

Authentication limitation: This server currently supports password or app-password authentication only, not OAuth2
Use app passwords where supported: Never use your primary account password when a provider offers a scoped app password
Require transport encryption: IMAP requires implicit TLS. SMTP uses implicit TLS when SMTP_SECURE=true and requires STARTTLS before authentication when it is false
Keep certificate verification enabled: Leave both TLS REJECT_UNAUTHORIZED settings at their default true unless you control and explicitly trust a private certificate authority
Protect stored credentials: MCP clients may save EMAIL_PASS in their local configuration. Restrict file permissions and never commit credentials to version control
Keep local env files private: .env and .env.* are ignored by Git; use a sanitized .env.example only when sharing configuration templates

Development

Development and runtime require Node.js 22.13 or newer. The repository pins Node.js 22.23.0 LTS in .nvmrc for local development.

Interactive testing with MCP Inspector

Run:

npm run dev:inspector

The command builds the project and opens the version-pinned MCP Inspector 1.0.0 UI. In the connection pane, configure:

Transport Type: STDIO
Command: node
Arguments: dist/index.js
Environment Variables: the IMAP, SMTP, username, and password variables listed above

Click Connect, open Tools, and call check_connection to verify IMAP and SMTP before testing search, read, or send tools. Other tools auto-connect as needed. Attachment tools also require MAIL_ALLOWED_ROOTS.

The MCP server and the version-pinned Inspector both require Node.js 22.13 or newer.

Release notes

See CHANGELOG.md for the complete version history.

Star History

Contributing

Bug reports, feature ideas, and pull requests are welcome. Start with the issue tracker or open a pull request directly.

License

Released under the MIT License.

View this README on GitHub

설치

npx -y mcp-mail-server

설정

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "[email protected]",
        "EMAIL_ADDRESS": "[email protected]",
        "EMAIL_PASS": "your-app-password"
      }
    }
  }
}