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.

1. Clone the repository:

   git clone https://github.com/u1pns/sendmail-mcp.git
   cd sendmail-mcp
   

2. Install dependencies:

   npm install
   

3. Configure Environment Variables: You can pass the environment variables directly in your MCP client's configuration file (preferred for portability) or use a .env file in the project's root directory.

   • Using env block in client config (Recommended):

     Gemini CLI (settings.json)

     Add this to your mcpServers object in the .gemini/settings.json file:

     {
       "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.js with the full path to your cloned index.js file on your computer (e.g., /Users/jpons/mcp/sendmail-mcp/index.js).

     Claude Desktop (claude_desktop_config.json)

     Add this to your mcpServers object:

     {
       "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"
           }
         }
       }
     }
     

   • Using a .env file (Alternative for local setup):

     1. Create a .env file in the root of the sendmail-mcp directory (use .env.example as a template).
     2. Fill in your SMTP credentials in the .env file.
     3. Configure your MCP client to just run the script without the env block.

     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 .env file located in the same directory as index.js.

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-mcp package 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.com saying 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:

1. Clone the repository:

   git clone <your-repo-url>
   cd mail-mcp
   

2. Install dependencies:

   npm install
   

3. Local Testing: You can create a .env file 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_PORT is 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.