imap-smtp-mcp

Universal IMAP/SMTP ↔ MCP bridge. Expose any IMAP mailbox and SMTP relay asModel Context Protocol tools, so anyMCP-compatible agent (Claude Code, Hermes, your own scripts) can read,search, send, and manage email.

┌──────────────────┐  httpStream + SSE  ┌──────────────────┐  IMAP   ┌────────────┐
│  MCP client      │ ──────────────────►│ imap-smtp-mcp    │ ───────►│ Mail       │
│  (Claude,        │                    │ (this server)    │         │ server     │
│   Hermes, etc.)  │                    │                  │  SMTP   │ (any)      │
└──────────────────┘                    └──────────────────┘ ───────►└────────────┘

✨ Features

8 MCP tools: server_info, list_mailboxes, list_emails,read_email, search_emails, send_email, mark_read, delete_email.
Universal: works with any IMAP/SMTP server (Gmail, Outlook, Fastmail,ProtonMail, Dovecot, Stalwart, Postfix, etc.).
Transport: FastMCP 3.x with httpStream (per-session, server-sent events)and stdio (for desktop integration).
Production-ready: graceful shutdown, persistent connections, structuredlogging, error handling.
No secrets in code: configuration via environment variables only.

📦 Installation

Prerequisites

Node.js ≥ 18
An IMAP/SMTP-enabled mailbox
For Gmail/Yahoo/Microsoft: an app password (not your account password).See provider-specific notes below.

From npm (once published)

npm install -g imap-smtp-mcp
imap-smtp-mcp

From source

git clone https://github.com/YOUR_USERNAME/imap-smtp-mcp.git
cd imap-smtp-mcp
npm install
npm run build
npm start

Development mode (with hot reload)

npm run dev

⚙️ Configuration

All configuration is via environment variables. Create a .env file orexport them in your shell / systemd unit.

Required

Variable	Description
`IMAP_HOST`	IMAP server hostname (e.g. `imap.gmail.com`)
`IMAP_USER`	IMAP username (often your full email address)
`IMAP_PASS`	IMAP password or app password
`SMTP_HOST`	SMTP server hostname (often same as IMAP host)
`SMTP_USER`	SMTP username
`SMTP_PASS`	SMTP password or app password

Optional

Variable	Default	Description
`IMAP_PORT`	`993`	IMAP port (993 for SSL, 143 for STARTTLS)
`IMAP_SECURE`	`true`	Use TLS (set `false` for STARTTLS or plaintext)
`IMAP_REJECT_UNAUTHORIZED`	`false`	Reject invalid TLS certs (set `true` for production)
`SMTP_PORT`	`465`	SMTP port (465 for SSL, 587 for STARTTLS)
`SMTP_SECURE`	`true`	Use TLS
`SMTP_REJECT_UNAUTHORIZED`	`false`	Reject invalid TLS certs
`SMTP_FROM`	`SMTP_USER`	"From" address (if different from SMTP_USER)
`FASTMCP_TRANSPORT`	`httpStream`	`httpStream` or `stdio`
`FASTMCP_PORT`	`3143`	HTTP port (only for httpStream)
`FASTMCP_HOST`	`0.0.0.0`	Bind address (use `127.0.0.1` for local-only)
`LOG_LEVEL`	`info`	`fatal`, `error`, `warn`, `info`, `debug`, `trace`
`LOG_DIR`	`./logs`	Directory for log files

Example `.env`

IMAP_HOST=imap.gmail.com
[email protected]
IMAP_PASS=abcd efgh ijkl mnop
IMAP_PORT=993
IMAP_SECURE=true
IMAP_REJECT_UNAUTHORIZED=true

SMTP_HOST=smtp.gmail.com
[email protected]
SMTP_PASS=abcd efgh ijkl mnop
SMTP_PORT=465
SMTP_SECURE=true

FASTMCP_TRANSPORT=httpStream
FASTMCP_PORT=3143
FASTMCP_HOST=0.0.0.0

LOG_LEVEL=info
LOG_DIR=/var/log/imap-smtp-mcp

🚀 Usage

As a daemon (recommended)

Once configured, just run:

imap-smtp-mcp
# [INFO] HTTP Stream listening on http://0.0.0.0:3143/mcp

With systemd

# /etc/systemd/system/imap-smtp-mcp.service
[Unit]
Description=IMAP/SMTP MCP Server
After=network.target

[Service]
Type=simple
User=imap-smtp
EnvironmentFile=/etc/imap-smtp-mcp.env
ExecStart=/usr/bin/node /opt/imap-smtp-mcp/dist/index.js
Restart=always
RestartSec=10
StandardOutput=append:/var/log/imap-smtp-mcp/mcp.log
StandardError=append:/var/log/imap-smtp-mcp/mcp.err.log

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now imap-smtp-mcp
systemctl status imap-smtp-mcp

With Docker

FROM node:20-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY dist ./dist
ENV NODE_ENV=production
EXPOSE 3143
CMD ["node", "dist/index.js"]

docker run -d --name imap-smtp-mcp \
  -p 3143:3143 \
  --env-file ./.env \
  imap-smtp-mcp:latest

As an MCP client (Claude Code, etc.)

{
  "mcpServers": {
    "mail": {
      "url": "http://localhost:3143/mcp"
    }
  }
}

For a remote server, replace localhost with the host:

{
  "mcpServers": {
    "mail": {
      "url": "http://localhost:3143/mcp"
    }
  }
}

As stdio (alternative)

If you prefer stdio transport (one process per session, e.g. for local desktop):

{
  "mcpServers": {
    "mail": {
      "command": "node",
      "args": ["/path/to/imap-smtp-mcp/dist/index.js"],
      "env": {
        "FASTMCP_TRANSPORT": "stdio",
        "IMAP_HOST": "imap.gmail.com",
        "IMAP_USER": "[email protected]",
        "IMAP_PASS": "..."
      }
    }
  }
}

🧰 Tools reference

`server_info`

Returns IMAP/SMTP server details and inbox counts.

{
  "user": "[email protected]",
  "imap": "imap.example.com:993",
  "smtp": "smtp.example.com:465",
  "inbox_total": 42,
  "inbox_unread": 7
}

`list_mailboxes`

Lists all mailboxes with message counts.

[
  { "name": "INBOX", "total": 42, "unread": 7 },
  { "name": "Sent", "total": 15, "unread": 0 },
  { "name": "Drafts", "total": 0, "unread": 0 }
]

`list_emails`

Lists emails in a mailbox.

Param	Type	Default	Description
`mailbox`	string	`INBOX`	Mailbox name
`limit`	number	`20`	Max results (1-500)
`unread_only`	boolean	`false`	Only return unread emails

[
  {
    "uid": 1234,
    "subject": "Hello",
    "from": "[email protected]",
    "to": "[email protected]",
    "date": "2026-07-25T18:00:00.000Z",
    "flags": ["\\Seen"],
    "preview": "First 200 chars of body..."
  }
]

`read_email`

Reads a full email by UID.

Param	Type	Description
`uid`	number	Email UID (from `list_emails`)
`mailbox`	string	Mailbox name (default `INBOX`)

Returns the email with full body. body is parsed as text/plain from the MIME source.

`search_emails`

Searches emails by keyword (matches body text).

Param	Type	Default	Description
`query`	string	(required)	Keyword
`mailbox`	string	`INBOX`	Mailbox
`limit`	number	`20`	Max results

`send_email`

Sends an email via SMTP.

Param	Type	Description
`to`	string	Recipient address
`subject`	string	Subject line
`body`	string	Plain-text body

Returns { status: "sent", to, subject, messageId }.

`mark_read`

Marks an email as read or unread.

Param	Type	Default	Description
`uid`	number	(required)	Email UID
`mailbox`	string	`INBOX`	Mailbox
`read`	boolean	`true`	`true`=read, `false`=unread

`delete_email`

Marks an email as deleted and expunges it. Permanent.

Param	Type	Default	Description
`uid`	number	(required)	Email UID
`mailbox`	string	`INBOX`	Mailbox

📧 Provider notes

Gmail

Enable 2FA on your Google account
Create an app password
Use the app password as IMAP_PASS / SMTP_PASS

IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_SECURE=true

Outlook / Microsoft 365

Enable 2FA on your Microsoft account
Create an app password via Microsoft account security
IMAP_USER should be your full email address

IMAP_HOST=outlook.office365.com
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST=smtp.office365.com
SMTP_PORT=587
SMTP_SECURE=false    # STARTTLS, not implicit TLS

Fastmail

IMAP_HOST=imap.fastmail.com
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST=smtp.fastmail.com
SMTP_PORT=465
SMTP_SECURE=true

ProtonMail Bridge

Run ProtonMail Bridge locally, then:

IMAP_HOST=127.0.0.1
IMAP_PORT=1143
IMAP_SECURE=false
SMTP_HOST=127.0.0.1
SMTP_PORT=1025
SMTP_SECURE=false
IMAP_USER=your-bridge-username
IMAP_PASS=your-bridge-password

Self-hosted (Dovecot, Stalwart, Postfix, etc.)

For self-hosted mail servers with self-signed certificates:

IMAP_REJECT_UNAUTHORIZED=false
SMTP_REJECT_UNAUTHORIZED=false

For production with valid certificates (Let's Encrypt), set both to true.

Yahoo Mail

IMAP_HOST=imap.mail.yahoo.com
SMTP_HOST=smtp.mail.yahoo.com

Generate an app password in Yahoo Account Security.

🛠️ Development

Scripts

npm run build       # Compile TypeScript to dist/
npm run dev         # Watch mode with tsx
npm run lint        # ESLint
npm test            # Run unit tests (vitest)
npm run test:watch  # Tests in watch mode
npm run format      # Prettier

Project layout

src/
  index.ts         # Entry point
  config.ts        # Env loading + Zod validation
  logger.ts        # Pino logger setup
  mail-service.ts  # IMAP/SMTP operations
  tools.ts         # MCP tool definitions
tests/
  config.test.ts   # Config validation tests
  mail-service.test.ts  # MailService with mocks
  tools.test.ts    # Tool registration + dispatch
.github/
  workflows/
    ci.yml         # Lint + test + build on Node 18/20/22

Adding a new tool

Add a method to MailService (in src/mail-service.ts).
Register the tool in registerMailTools (in src/tools.ts).
Add a test in tests/tools.test.ts.

🔒 Security

No secrets in code. All credentials come from environment variables.
Use app passwords, not account passwords, for Gmail/Outlook/Yahoo.
For production, set IMAP_REJECT_UNAUTHORIZED=true andSMTP_REJECT_UNAUTHORIZED=true with valid certificates.
Bind FASTMCP_HOST=127.0.0.1 if the MCP client runs on the same host.
For remote access, place behind a reverse proxy (nginx) with TLS.

📜 License

MIT — see LICENSE.

🤝 Contributing

Issues and pull requests welcome. Please run npm run lint && npm test beforesubmitting.