SMTP MCP Server
The SMTP MCP Server is a versatile email management system that allows you to:
Send Emails: Send individual or bulk emails with HTML support, CC/BCC options, template variables, and rate-limited batching
Manage SMTP Configurations: Add, update, delete, and retrieve SMTP server settings
Handle Email Templates: Create and manage reusable templates with dynamic variables
Monitor Activity: View logs of all email sending activity with optional filtering
Provides SMTP configuration for Gmail as an email sending service that can be used by the MCP server
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SMTP MCP Serversend a welcome email to alex@example.com using the welcome template"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Email SMTP/IMAP MCP
One local MCP server for every inbox: search, read, send, reply, forward, and organize email across multiple accounts.
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.jsonWindows:
%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 |
| List every configured account and identify the default without exposing credentials. |
| Search by text, sender, recipient, subject, date, read state, flag state, or attachments. Optionally return bodies and attachments. |
| Send plain-text or HTML email with CC, BCC, sender aliases, and base64 attachments. |
| Reply, reply-all, or forward by email UID with threading and optional original attachments. |
| Mark read/unread, flag/unflag, or move messages to another folder. |
| 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:
“List my configured email accounts.”
“List folders for my
workaccount.”“Find the five newest unread emails in my
personalaccount.”“Send a plain-text email from my
workaccount.”
Provider settings
Provider | SMTP | IMAP | Credential |
Gmail |
|
| |
iCloud Mail |
|
| |
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 testRun 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 toolsaccounts_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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Array of recipient emails (required for 'forward', optional for replies to override default recipients) | |
| body | Yes | Your response message content | |
| email_id | Yes | ID of the email to respond to (from emails_find results) | |
| body_type | No | Response body format | html |
| account_name | No | Name of the email account to use | |
| response_type | No | 'reply' to sender only, 'reply_all' to all recipients, or 'forward' to new recipients | reply |
| include_original | No | Include the original email content in your response | |
| include_attachments | No | Include attachments from the original email | |
| additional_attachments | No | Additional attachments to include |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | Array of CC recipient email addresses | |
| to | Yes | Array of recipient email addresses | |
| bcc | No | Array of BCC recipient email addresses | |
| body | Yes | Email body content (can be plain text or HTML) | |
| subject | Yes | Email subject line | |
| body_type | No | Body format: 'plain' for plain text or 'html' for HTML content | html |
| from_email | No | Optional sender address. When sender_emails is configured for the account, the address must be in that allowlist. | |
| attachments | No | Array of file attachments | |
| account_name | No | Name of the email account to use |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of emails to return (1-100) | |
| query | No | Text to search across subject, body, sender, and recipients (e.g., 'project update') | |
| filters | No | Structured filters for precise email search | |
| account_name | No | Name of the email account to use (e.g., 'work', 'personal'). If not provided, uses the default account. | |
| include_content | No | Include full email body content in results | |
| include_attachments | No | Include attachment content (base64 encoded) |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| flag | No | Flag/star emails as important | |
| unflag | No | Remove flag/star from emails | |
| email_ids | Yes | Array of email IDs to modify (from emails_find results) | |
| mark_read | No | Mark emails as read | |
| mark_unread | No | Mark emails as unread | |
| account_name | No | Name of the email account to use | |
| move_to_folder | No | Move emails to a folder (e.g., 'Archive', 'Trash', 'INBOX') |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| account_name | No | Name of the email account to use | |
| include_counts | No | Include unread and total message counts for each folder |
TDQS
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.
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.
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.
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.
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.
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.
17 tool updates
v2.2.0- Added
accounts_list - Removed
add-email-template - Removed
add-smtp-config - Removed
delete-email-template - Removed
delete-smtp-config - Added
email_respond - Added
email_send - Added
emails_find - Added
emails_modify - Added
folders_list - Removed
get-email-logs - Removed
get-email-templates - Removed
get-smtp-configs - Removed
send-bulk-emails - Removed
send-email - Removed
update-email-template - Removed
update-smtp-config
11 tool updates
v1.0.0- Added
add-email-template - Added
add-smtp-config - Added
delete-email-template - Added
delete-smtp-config - Added
get-email-logs - Added
get-email-templates - Added
get-smtp-configs - Added
send-bulk-emails - Added
send-email - Added
update-email-template - Added
update-smtp-config
TDQS
Scored across 6 tools
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.
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.
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.
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
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
Send transactional emails for AI agents via SMTP. Templates included.
Send, track, and manage transactional and bulk email delivery
Send transactional email over a verified domain — templates, attachments, custom headers.
Send email and read templates, marketing contacts, lists, stats, bounces and unsubscribes.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables 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.-
- AlicenseNot gradedqualityDmaintenanceEnables sending emails through SMTP using nodemailer, allowing AI assistants to send plain text and HTML emails with configurable SMTP credentials.192ISC
- AlicenseNot gradedqualityDmaintenanceEnables sending and receiving emails through SMTP, IMAP, and POP3 protocols with support for attachments, HTML content, and email validation.MIT
- FlicenseAqualityDmaintenanceEnables 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-