Mail SMTP MCP Server

How to use

Use an MCP client to interact with the mail-smtp-mcp server by selecting one of the available tools and providing the required inputs. You can list configured SMTP accounts, verify connectivity, or send outbound messages with optional attachments. Sending is gated by a feature flag, and you can perform a dry run to validate payloads and policy without actually sending.

How to install

Prerequisites: you need Node.js and a package manager (npm, pnpm, or npx) installed on your machine.

Install dependencies and start the server for development.

pnpm install
pnpm dev

To build a production bundle and run the built server.

pnpm build

# Run the built server (example path shown for a typical project structure)
node dist/index.js

If you prefer to run via a local development workflow without building.

pnpm install
pnpm dev

Configuration and usage notes

Configure SMTP accounts and policies using environment variables. The server can load a local .env file. Do not commit secrets. You can start with a default account and expand to additional accounts as needed.

Key environment variables shown in examples include default host, user, password, and sender address. You can enable the send capability and define allowlists to restrict recipients or domains.

Example MCP server configuration for starting from a runnable command (adjust paths to your environment). The following config shows a built server started with Node and a dist index, with environment variables providing SMTP credentials and enabling sending.

{
  "command": "node",
  "args": ["dist/index.js"],
  "env": {
    "MAIL_SMTP_DEFAULT_HOST": "smtp.example.com",
    "MAIL_SMTP_DEFAULT_USER": "[email protected]",
    "MAIL_SMTP_DEFAULT_PASS": "app-password-or-token",
    "MAIL_SMTP_SEND_ENABLED": "true"
  }
}

Security and safety notes

Sending is gated by a flag and inputs are validated to reject header injection and enforce size limits. Use dry_run to validate payloads before sending. Do not log or return credentials; outputs include only non-secret metadata.

If you enable an allowlist, only recipients that match the allowed domains or addresses can be used.

Tools and data flow

This MCP server provides three primary tools that you will invoke from a client:

• mail_smtp_list_accounts: List configured SMTP accounts and their non-secret metadata.

• mail_smtp_verify_account: Verify that a configured SMTP account can connect and authenticate.

• mail_smtp_send_message: Send an outbound email via SMTP or validate inputs with dry_run; supports text and HTML bodies and optional attachments.

Example MCP server configuration snippets

{
  "command": "node",
  "args": ["dist/index.js"],
  "env": {
    "MAIL_SMTP_DEFAULT_HOST": "smtp.example.com",
    "MAIL_SMTP_DEFAULT_USER": "[email protected]",
    "MAIL_SMTP_DEFAULT_PASS": "app-password-or-token",
    "MAIL_SMTP_SEND_ENABLED": "true"
  }
}

Appendix: frequently used environment variables

If you use multiple accounts, define separate host/user/password combinations per account. Use the default account to keep things simple, and extend with additional accounts as needed.

Troubleshooting

If you encounter issues with sending, verify that MAIL_SMTP_SEND_ENABLED is true, confirm credentials are correct, and check network access to the SMTP host. Use dry_run to validate payloads before attempting to send.

mail_smtp_list_accounts

List configured SMTP accounts and expose non-secret metadata.

mail_smtp_verify_account

Verify a configured SMTP account can connect and authenticate.

mail_smtp_send_message

Send or validate an outbound email via SMTP, with optional attachments and dry_run mode.