Mail MCP Server
A Model Context Protocol (MCP) server that provides email sending capabilities using Nodemailer. This server allows AI agents (like Gemini CLI, Claude, etc.) to send emails on your behalf using your own SMTP credentials.
Features
- Send Email: Send plain text and HTML emails to any recipient.
- Secure: Uses your own SMTP server credentials (Gmail, Outlook, AWS SES, etc.).
- Logging: Automatically logs email activities to daily files in the
log/directory for audit and debugging.
Prerequisites
- Node.js: v14 or higher.
- SMTP Credentials: Host, port, user, and password for your email provider.
MCP Client Configuration
To use this server with your MCP client, you need to configure it to run the index.js script. You have two main ways to integrate and provide your SMTP credentials:
Option 1: Local Installation (Recommended for Development)
This method is ideal when you're developing locally or want to run the server directly from its cloned repository. You will provide the absolute path to the index.js file.
-
Clone the repository:
git clone https://github.com/u1pns/sendmail-mcp.git cd sendmail-mcp -
Install dependencies:
npm install -
Configure Environment Variables: You can pass the environment variables directly in your MCP client's configuration file (preferred for portability) or use a
.envfile in the project's root directory.-
Using
envblock in client config (Recommended):Gemini CLI (
settings.json)Add this to your
mcpServersobject in the.gemini/settings.jsonfile:{ "mcpServers": { "sendmail-mcp": { "command": "node", "args": ["/absolute/path/to/sendmail-mcp/index.js"], "env": { "SMTP_HOST": "smtp.example.com", "SMTP_PORT": "465", "SMTP_SECURE": "true", "SMTP_USER": "your_email@example.com", "SMTP_PASS": "your_password", "MAIL_FROM": "sender@example.com" } } } }- Important: Replace
/absolute/path/to/sendmail-mcp/index.jswith the full path to your clonedindex.jsfile on your computer (e.g.,/Users/jpons/mcp/sendmail-mcp/index.js).
Claude Desktop (
claude_desktop_config.json)Add this to your
mcpServersobject:{ "mcpServers": { "sendmail-mcp": { "command": "node", "args": ["/absolute/path/to/sendmail-mcp/index.js"], "env": { "SMTP_HOST": "smtp.example.com", "SMTP_PORT": "465", "SMTP_SECURE": "true", "SMTP_USER": "your_email@example.com", "SMTP_PASS": "your_password", "MAIL_FROM": "sender@example.com" } } } } - Important: Replace
-
Using a
.envfile (Alternative for local setup):- Create a
.envfile in the root of thesendmail-mcpdirectory (use.env.exampleas a template). - Fill in your SMTP credentials in the
.envfile. - Configure your MCP client to just run the script without the
envblock.
Generic Configuration (Gemini/Claude)
{ "mcpServers": { "sendmail-mcp": { "command": "node", "args": ["/absolute/path/to/sendmail-mcp/index.js"] } } }The server will automatically load the credentials from the
.envfile located in the same directory asindex.js. - Create a
-
Option 2: Using npx
This method is similar to how chrome-devtools-mcp is used, where you can reference the package directly via npx after it has been published to the npm registry. This provides a more convenient and globally accessible way to use the server.
- Prerequisite: This
sendmail-mcppackage must be published to npm (e.g.,npm publish).
Gemini CLI (settings.json)
Add this to your mcpServers object in the .gemini/settings.json file:
{
"mcpServers": {
"sendmail-mcp": {
"command": "npx",
"args": ["sendmail-mcp@latest"],
"env": {
"SMTP_HOST": "smtp.example.com",
"SMTP_PORT": "465",
"SMTP_SECURE": "true",
"SMTP_USER": "your_email@example.com",
"SMTP_PASS": "your_password",
"MAIL_FROM": "sender@example.com"
}
}
}
}
Claude Desktop (claude_desktop_config.json)
Add this to your mcpServers object:
{
"mcpServers": {
"sendmail-mcp": {
"command": "npx",
"args": ["sendmail-mcp@latest"],
"env": {
"SMTP_HOST": "smtp.example.com",
"SMTP_PORT": "465",
"SMTP_SECURE": "true",
"SMTP_USER": "your_email@example.com",
"SMTP_PASS": "your_password",
"MAIL_FROM": "sender@example.com"
}
}
}
}
Environment Variables Reference
Regardless of the method you use, these are the variables you need to set:
| Variable | Description | Example |
|---|---|---|
SMTP_HOST | Hostname of your SMTP server | smtp.gmail.com |
SMTP_PORT | Port number (usually 465 for SSL or 587 for TLS) | 465 |
SMTP_SECURE | Set to true for port 465, false for others | true |
SMTP_USER | Your email username | user@gmail.com |
SMTP_PASS | Your email password (or App Password) | secret |
MAIL_FROM | The email address to send from | user@gmail.com |
Tools
This server exposes a single tool to the MCP client:
send_email
Sends an email using the configured SMTP server.
Inputs:
to(string, required): The recipient's email address.subject(string, required): The subject line of the email.text(string, required): The plain text content of the email.html(string, optional): The HTML content of the email (for rich text).
Usage
Once configured, you can use natural language to interact with the server through your AI agent.
Example Prompts:
"Send an email to
boss@company.comsaying I'll be late to the meeting."
"Email the weekly report to the team with the subject 'Weekly Status' and the body 'All systems go'."
"Send a test email to myself to verify the SMTP connection."
Development
If you want to modify or contribute to this project:
-
Clone the repository:
git clone <your-repo-url> cd mail-mcp -
Install dependencies:
npm install -
Local Testing: You can create a
.envfile for local testing during development (though the MCP client configuration handles env vars in production usage).cp .env.example .env
Server Lifecycle
It's important to understand that this MCP server operates as a child process of your MCP client (e.g., Gemini CLI). This means:
- Starts with Client: The server process is automatically launched by the MCP client when the client starts or when it first needs to interact with the server's tools.
- Stops with Client: When you close your MCP client (e.g., exit Gemini CLI), the client will automatically terminate the server process. It does not run indefinitely in the background.
Troubleshooting
- Authentication Failed: If using Gmail, ensure you have 2-Factor Authentication enabled and are using an App Password, not your main password.
- Connection Refused: Check your firewall settings and ensure
SMTP_PORTis correct. - Logs: Check the
log/directory in the project folder. Logs are rotated daily (e.g.,2025-12-01.log).
License
MIT License
Copyright (c) 2025
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.