Skip to main content
Glama
samihalawa

SMTP MCP Server

by samihalawa

Email SMTP/IMAP MCP

One local MCP server for every inbox: search, read, send, reply, forward, and organize email across multiple accounts.

release npm downloads CI Node.js stars license

Why this server

  • No account-count cap — add work, personal, support, or client inboxes and switch with account_name.

  • SMTP + IMAP together — send and receive through one small MCP server.

  • Complete everyday workflow — search, read, reply, forward, attach files, flag, archive, move, and list folders.

  • Provider-agnostic — works with Gmail, iCloud Mail, Fastmail, Outlook, self-hosted mail, and other standard SMTP/IMAP providers.

  • Local stdio transport — no hosted relay and no separate control panel.

Related MCP server: Email MCP Server

Quick start

1. Create your .env

Copy .env.example to a private location and add as many named accounts as you need:

EMAIL_ACCOUNTS_JSON='{
  "work": {
    "smtp": {
      "host": "smtp.gmail.com",
      "port": 587,
      "secure": false,
      "user": "work@example.com",
      "password": "app-password"
    },
    "imap": {
      "host": "imap.gmail.com",
      "port": 993,
      "secure": true,
      "user": "work@example.com",
      "password": "app-password"
    },
    "default_from_name": "Your Name",
    "sender_emails": ["work@example.com", "alias@example.com"]
  },
  "personal": {
    "smtp": {
      "host": "smtp.mail.me.com",
      "port": 587,
      "secure": false,
      "user": "you@icloud.com",
      "password": "app-password"
    },
    "imap": {
      "host": "imap.mail.me.com",
      "port": 993,
      "secure": true,
      "user": "you@icloud.com",
      "password": "app-password"
    }
  }
}'

DEFAULT_EMAIL_ACCOUNT="work"

The server loads .env from its working directory automatically. EMAIL_ENV_FILE lets an MCP client use an .env stored anywhere.

2. Add the MCP server

For Claude Desktop, edit:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["-y", "email-smtp-imap-mcp"],
      "env": {
        "EMAIL_ENV_FILE": "/absolute/path/to/your/.env"
      }
    }
  }
}

Use an absolute path, restart your MCP client, then ask: “List my configured email accounts.”

You can skip the .env file and set EMAIL_ACCOUNTS_JSON plus DEFAULT_EMAIL_ACCOUNT directly in the MCP client’s env object. The JSON must be escaped into a single string.

{
  "env": {
    "EMAIL_ACCOUNTS_JSON": "{\"work\":{\"smtp\":{\"host\":\"smtp.gmail.com\",\"port\":587,\"user\":\"work@example.com\",\"password\":\"app-password\"},\"imap\":{\"host\":\"imap.gmail.com\",\"port\":993,\"user\":\"work@example.com\",\"password\":\"app-password\"}}}",
    "DEFAULT_EMAIL_ACCOUNT": "work"
  }
}

Use SMTP_HOST, SMTP_PORT, SMTP_SECURE, SMTP_USER, SMTP_PASS, IMAP_HOST, IMAP_PORT, IMAP_SECURE, IMAP_USER, and IMAP_PASS instead of EMAIL_ACCOUNTS_JSON.

SMTP_USERNAME/SMTP_PASSWORD and IMAP_USERNAME/IMAP_PASSWORD are accepted aliases. IMAP credentials default to the SMTP credentials when omitted. Use SENDER_EMAILS as a comma-separated allowlist for optional from_email selection.

Tools

Tool

What it does

accounts_list

List every configured account and identify the default without exposing credentials.

emails_find

Search by text, sender, recipient, subject, date, read state, flag state, or attachments. Optionally return bodies and attachments.

email_send

Send plain-text or HTML email with CC, BCC, sender aliases, and base64 attachments.

email_respond

Reply, reply-all, or forward by email UID with threading and optional original attachments.

emails_modify

Mark read/unread, flag/unflag, or move messages to another folder.

folders_list

List folders with optional total and unread counts.

Every email tool accepts an optional account_name. Without it, the server uses DEFAULT_EMAIL_ACCOUNT or the first configured account. There is no application-level account-count limit.

Verify your setup

After restarting the MCP client, try these in order:

  1. “List my configured email accounts.”

  2. “List folders for my work account.”

  3. “Find the five newest unread emails in my personal account.”

  4. “Send a plain-text email from my work account.”

Provider settings

Provider

SMTP

IMAP

Credential

Gmail

smtp.gmail.com:587

imap.gmail.com:993

App password

iCloud Mail

smtp.mail.me.com:587

imap.mail.me.com:993

App-specific password

Other providers

Use the provider's SMTP host

Use the provider's IMAP host

Provider password or app password

Use secure: true for implicit TLS ports such as 465/993. Port 587 normally uses secure: false and upgrades with STARTTLS.

Development

git clone https://github.com/samihalawa/email-smtp-imap-mcp.git
cd email-smtp-imap-mcp
npm ci
npm test

Run the compiled stdio server with npm start. Build a production container with docker build -t email-smtp-imap-mcp ..

Contributing

Issues and focused pull requests are welcome. See CONTRIBUTING.md for the development workflow and SECURITY.md for vulnerability reports.

License

MIT © Sami Halawa

Available Tools

6 tools
accounts_listA

List every configured email account and show which account is the default. Use this before other tools when multiple SMTP/IMAP accounts are configured.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It clearly states the read-only nature of listing accounts and adds the non-obvious detail that it identifies the default account, which is useful behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action, and contains no filler. Every sentence contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter list tool, the description fully covers its purpose, output behavior (list and default), and usage context. No output schema exists, but the simplicity of the tool means the description is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the schema covers 100% (empty properties). With no parameters, the description does not need to add parameter-level detail; the baseline of 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('every configured email account'), and clarifies the secondary function of showing the default account. This clearly distinguishes it from the sibling tools, which deal with folders, emails, and sending.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when to use this tool ('before other tools when multiple SMTP/IMAP accounts are configured'), giving both a timing recommendation and a condition for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

email_respondA

Reply to or forward an existing email. Use this to continue email conversations, respond to messages, or forward information to others.

ParametersJSON Schema
NameRequiredDescriptionDefault
toNoArray of recipient emails (required for 'forward', optional for replies to override default recipients)
bodyYesYour response message content
email_idYesID of the email to respond to (from emails_find results)
body_typeNoResponse body formathtml
account_nameNoName of the email account to use
response_typeNo'reply' to sender only, 'reply_all' to all recipients, or 'forward' to new recipientsreply
include_originalNoInclude the original email content in your response
include_attachmentsNoInclude attachments from the original email
additional_attachmentsNoAdditional attachments to include

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden for behavioral disclosure. It fails to mention that this tool sends an email (a consequential, irreversible action), nor does it discuss permissions, delivery semantics, or failure handling. The description is purely functional and lacks transparency about side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loads the core action, and contains no filler or redundant information. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 9 parameters, no output schema, and no annotations, the description is minimal. It gives a basic orientation but does not offer guidance on complex behaviors like reply-all vs forward, attachment handling, or account selection, leaving the agent to rely solely on the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the description does not need to explain parameters in detail. The description adds only high-level context ('reply', 'forward') that aligns with the schema's parameter definitions, providing no extra semantic value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action ('Reply to or forward') on a specific resource ('an existing email'), and the phrase 'existing email' helps distinguish from sending a new email. However, it does not explicitly name sibling tools like email_send, so it lacks full differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear use cases: 'continue email conversations, respond to messages, or forward information to others.' This gives context for when to use the tool, but it does not explicitly mention when not to use it or point to alternatives like email_send for composing new emails.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

email_sendA

Send a new email with HTML support and file attachments. Use this to send messages, project updates, or any new email conversation.

ParametersJSON Schema
NameRequiredDescriptionDefault
ccNoArray of CC recipient email addresses
toYesArray of recipient email addresses
bccNoArray of BCC recipient email addresses
bodyYesEmail body content (can be plain text or HTML)
subjectYesEmail subject line
body_typeNoBody format: 'plain' for plain text or 'html' for HTML contenthtml
from_emailNoOptional sender address. When sender_emails is configured for the account, the address must be in that allowlist.
attachmentsNoArray of file attachments
account_nameNoName of the email account to use

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, but it only repeats schema details like HTML support and attachments. It does not disclose side effects, authentication requirements, or other behavioral traits beyond what the schema already lists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the main action, and no wasted words. Every sentence serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 9 parameters and no output schema, the description is too thin. It omits any information about return values, potential errors, or constraints like the sender allowlist noted in the schema's from_email property.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds no extra meaning beyond naming HTML and attachments, which are already in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Send a new email with HTML support and file attachments.' It distinguishes itself from sibling tools like email_respond by emphasizing 'new email conversation.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear usage context: 'Use this to send messages, project updates, or any new email conversation.' However, it doesn't explicitly exclude alternatives like email_respond, but the 'new email' phrasing implies the boundary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

emails_findA

Search for emails in your inbox with flexible filters. Optionally get full email content and attachments. Use this to find specific emails, check for unread messages, or browse your inbox.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of emails to return (1-100)
queryNoText to search across subject, body, sender, and recipients (e.g., 'project update')
filtersNoStructured filters for precise email search
account_nameNoName of the email account to use (e.g., 'work', 'personal'). If not provided, uses the default account.
include_contentNoInclude full email body content in results
include_attachmentsNoInclude attachment content (base64 encoded)

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It mentions optional content/attachments retrieval, which adds context, but it does not state whether the tool is read-only, how filters combine, or pagination behavior. It is adequate for a search tool but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose and followed by concrete use cases. There is no wasted wording, and it is appropriately sized for the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 params, nested filters) and lack of output schema, the description covers the main purpose and usage scenarios. However, it does not mention the return format or default behavior (e.g., limit), relying on the schema for those details. This is sufficient but leaves room for improvement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions cover all parameters (100% coverage), so the description adds little beyond reiterating the existence of filters and optional content/attachments. The phrase 'flexible filters' maps to the filters object, but the schema already details each filter field.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Search for emails in your inbox with flexible filters.' This is a specific verb+resource combination that distinguishes it from siblings like email_send and email_respond, though it does not explicitly name alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit use cases: 'Use this to find specific emails, check for unread messages, or browse your inbox.' This gives clear guidance on when to use the tool, though it does not explicitly state when not to use it or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

emails_modifyA

Change email states like read/unread, flagged, or move between folders. Use this to organize your inbox, mark emails as read, archive messages, or flag important emails.

ParametersJSON Schema
NameRequiredDescriptionDefault
flagNoFlag/star emails as important
unflagNoRemove flag/star from emails
email_idsYesArray of email IDs to modify (from emails_find results)
mark_readNoMark emails as read
mark_unreadNoMark emails as unread
account_nameNoName of the email account to use
move_to_folderNoMove emails to a folder (e.g., 'Archive', 'Trash', 'INBOX')

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden of behavioral transparency. It explains basic state changes but does not disclose potential side effects, permission requirements, or behavior with conflicting flags (e.g., mark_read=true and mark_unread=true together). It is not misleading, but lacks depth for a tool with multiple conditional actions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: two sentences that front-load the core purpose and then give practical use cases. There is no wasted text or redundancy. Every sentence contributes to understanding the tool's functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 7 parameters with potential conflicts and no output schema or annotations. The description does not address edge cases such as mutually exclusive flags or the effect of moving an email out of a folder. While the schema covers parameters, the behavioral context is partially incomplete for a moderately complex modification tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The description does not add additional parameter-level meaning beyond the schema. Baseline 3 is appropriate since the description gives general usage examples but no syntax or parameter-specific clarifications.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Change email states like read/unread, flagged, or move between folders.' It uses a specific verb ('change') and resource ('email states') and lists concrete examples. This distinguishes it from sibling tools like emails_find (search), email_send (send), and email_respond (reply), which handle different operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context on when to use the tool: 'Use this to organize your inbox, mark emails as read, archive messages, or flag important emails.' This implies appropriate scenarios without explicitly naming alternatives or exclusions. Given the sibling set, the use cases are clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

folders_listA

List all available email folders/labels in your account. Use this to see your folder structure and organize emails.

ParametersJSON Schema
NameRequiredDescriptionDefault
account_nameNoName of the email account to use
include_countsNoInclude unread and total message counts for each folder

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It states the primary behavior (listing folders) but does not add details about read-only nature, potential side effects, or the meaning of the optional include_counts parameter. For a simple list operation, the behavior is fairly transparent, but the description adds little beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences, front-loaded with the purpose and followed by a clear usage note. Every sentence earns its place with no fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with no output schema, the description provides adequate context: it tells what it lists and why to use it. It could mention the include_counts option or behavior when account_name is omitted, but the schema covers these details, and the overall purpose is clear.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does not discuss parameters, but the schema fully documents account_name and include_counts, so no additional explanation is required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'List all available email folders/labels in your account.' It uses a specific verb and resource, and is easily distinguished from sibling tools like accounts_list and emails_find, which focus on accounts and emails respectively.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: 'Use this to see your folder structure and organize emails.' It does not explicitly mention alternatives or exclusions, but the purpose is distinct enough that this is not a significant gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 17 tool updatesv2.2.0
    • Addedaccounts_list
    • Removedadd-email-template
    • Removedadd-smtp-config
    • Removeddelete-email-template
    • Removeddelete-smtp-config
    • Addedemail_respond
    • Addedemail_send
    • Addedemails_find
    • Addedemails_modify
    • Addedfolders_list
    • Removedget-email-logs
    • Removedget-email-templates
    • Removedget-smtp-configs
    • Removedsend-bulk-emails
    • Removedsend-email
    • Removedupdate-email-template
    • Removedupdate-smtp-config
  2. 11 tool updatesv1.0.0
    • Addedadd-email-template
    • Addedadd-smtp-config
    • Addeddelete-email-template
    • Addeddelete-smtp-config
    • Addedget-email-logs
    • Addedget-email-templates
    • Addedget-smtp-configs
    • Addedsend-bulk-emails
    • Addedsend-email
    • Addedupdate-email-template
    • Addedupdate-smtp-config

TDQS

A4/5.0

Scored across 6 tools

Disambiguation5/5

Each tool targets a distinct operation: account listing, folder listing, searching, modifying, sending, and responding. There is no overlap; even email_send and email_respond are clearly separated by new vs. reply/forward.

Naming Consistency4/5

Most tools follow a consistent resource_action pattern (e.g., accounts_list, emails_find). However, there is minor inconsistency in singular vs. plural usage (accounts_list vs. email_send) and action placement, but it remains readable.

Tool Count5/5

With 6 tools, the server is well-scoped for email operations. Each tool earns its place, covering account context, folder navigation, search, state changes, and message creation without redundancy.

Completeness5/5

The toolset covers the core email workflow: discover accounts and folders, find messages, modify their state, send new emails, and reply/forward. No essential operation is missing; even email deletion can be handled via moving to trash.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    Enables sending emails via SMTP with support for HTML content, attachments, bulk sending, and template-based emails. Features session management and full MCP Streamable HTTP transport compliance.
    -
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables sending emails through SMTP using nodemailer, allowing AI assistants to send plain text and HTML emails with configurable SMTP credentials.
    19
    2
    ISC
  • F
    license
    A
    quality
    D
    maintenance
    Enables sending emails through SMTP with support for multiple recipients, attachments, CC/BCC, and both plain text and HTML formats. Includes preset configurations for common email providers like Gmail, QQ, Outlook, and 163.
    5
    -