IMAP邮件管理MCP服务器

mcp-imap

An MCP (Model Context Protocol) server that exposes IMAP email operations as tools for AI assistants like Claude. Supports multiple accounts, Dovecot-optimised, and ships with a web UI for configuration.

Features

• Multiple accounts — configure as many IMAP/SMTP accounts as needed
• Read & manage email — list, get, move, archive, delete, flag
• Send email — compose, reply (with correct threading headers), reply-all
• Mailbox browsing — list all folders with message counts
• Search — full IMAP search by subject, sender, recipient, body text, date range, or flag
• Filters — unread-only, flagged-only, or all
• Hot reload — config changes are picked up without restarting
• Config UI — built-in web interface to manage accounts
• Transports — stdio (for Claude Desktop) and Streamable HTTP

Installation

Download a release

Download the latest binary for your platform from the Releases page and place it somewhere on your $PATH, e.g.:

# macOS (Apple Silicon)
curl -L https://github.com/user/mcp-imap/releases/latest/download/mcp-imap_Darwin_arm64.tar.gz | tar xz
mv mcp-imap /usr/local/bin/

Build from source

Requires Go 1.22+.

git clone https://github.com/user/mcp-imap.git
cd mcp-imap
just build          # binary written to ./dist/mcp-imap

Configuration

The config file lives at ~/.config/mcp-imap/config.toml.

Using the config UI

The easiest way to configure accounts is through the built-in web interface:

mcp-imap --ui
# Config UI available at http://localhost:3456

Open http://localhost:3456 in your browser, add your accounts, and click Save Config. The UI will test the connection before saving.

Manual configuration

Create ~/.config/mcp-imap/config.toml:

[[accounts]]
name = "personal"
archive_folder = "Archive"   # optional, default: "Archive"

[accounts.imap]
host     = "mail.example.com"
port     = 993
username = "you@example.com"
password = "your-password"
tls      = true

[accounts.smtp]
host     = "mail.example.com"
port     = 587
username = "you@example.com"
password = "your-password"
tls      = false
starttls = true

[[accounts]]
name = "work"

[accounts.imap]
host     = "imap.company.com"
port     = 993
username = "you@company.com"
password = "your-password"
tls      = true

[accounts.smtp]
host     = "smtp.company.com"
port     = 465
username = "you@company.com"
password = "your-password"
tls      = true   # implicit TLS on port 465
starttls = false

Port conventions:

Adding to Claude Desktop (stdio)

1. Make sure mcp-imap is on your PATH or note its full path:

   复制

   which mcp-imap
   # e.g. /usr/local/bin/mcp-imap
   

2. Open the Claude Desktop config file:

   Platform	Path
   macOS	~/Library/Application Support/Claude/claude_desktop_config.json
   Windows	%APPDATA%\Claude\claude_desktop_config.json

3. Add the server under mcpServers:

   复制

   {
     "mcpServers": {
       "mcp-imap": {
         "command": "/usr/local/bin/mcp-imap",
         "args": []
       }
     }
   }
   

   If you need to point to a custom config file:

   复制

   {
     "mcpServers": {
       "mcp-imap": {
         "command": "/usr/local/bin/mcp-imap",
         "args": ["--config", "/path/to/config.toml"]
       }
     }
   }
   

4. Restart Claude Desktop. The email tools should appear in the tool picker.

Streamable HTTP transport

For use with other MCP clients or reverse proxies:

mcp-imap --transport http --port 8080
# MCP IMAP server listening on :8080/mcp

The single endpoint is POST /mcp.

Environment variable equivalents:

MCPIMAP_TRANSPORT=http MCPIMAP_PORT=8080 mcp-imap

Available tools

Example: listing unread emails

email_list(mailbox="INBOX", filter="unread", limit=10)

Example: searching emails

email_search(mailbox="INBOX", from="alice@example.com", since="2026-01-01")
email_search(mailbox="INBOX", subject="invoice", has_flag="unseen")
email_search(mailbox="INBOX", body="project kickoff", before="2026-03-01", limit=20)

email_search parameters:

All criteria are combined with AND and evaluated server-side.

Example: getting email detail

email_get(email_id="43671", mailbox="INBOX")

Returns:

{
  "email_id": "43671",
  "subject": "Hello",
  "from": [{ "name": "Alice", "email": "alice@example.com" }],
  "to":   [{ "name": "Bob",   "email": "bob@example.com" }],
  "date": "2026-03-28T10:00:00+01:00",
  "flags": ["\\Seen"],
  "flagged": false,
  "seen": true,
  "message_id": "<abc123@mail.example.com>",
  "body_text": "Hi Bob, ...",
  "attachments": []
}

Development

just build      # build binary to ./dist/mcp-imap
just run-stdio  # run with stdio transport
just run-http   # run with HTTP transport on :8080
just ui         # open config UI on :3456
just tidy       # go mod tidy