Overview

This MCP (Model Context Protocol) server exposes an SMTP-based email tool that lets AI agents send emails with file attachments. It acts as a bridge between an agent and an SMTP mail server: the agent calls the MCP endpoint to request an email be sent and the server handles SMTP delivery, attachment encoding, and basic security checks. This enables agents to communicate results, deliver reports, or share files without embedding SMTP logic into the agent itself.

The server is useful when you want a centralized, auditable, and configurable way for agents to send messages or files. Rather than hard-coding SMTP details into many agents, you give them access to the MCP tool and control sending behavior (rate limits, allowed recipients, logging, attachments support) on the server side.

Features

Send plain text and HTML emails via SMTP
Attach files (multipart MIME, base64-encoded payloads)
Simple JSON-based MCP endpoint that agents call to send messages
Environment-based configuration for SMTP credentials and security settings
Optional Docker support for containerized deployment
Basic validation and recipient whitelisting to reduce abuse
Logging of send events for audit and debugging

Installation / Configuration

Prerequisites: Node.js >= 16 and an SMTP account (e.g., Gmail, Mailgun, SES SMTP settings).

Clone and install:

git clone https://github.com/egyptianego17/email-mcp-server.git
cd email-mcp-server
npm install

Environment variables

Create a .env with the following variables (example):

# SMTP configuration
SMTP_HOST=smtp.example.com
SMTP_PORT=587
[email protected]
SMTP_PASS=supersecretpassword
SMTP_SECURE=false   # true if using SMTPS (465)
[email protected]

# Server configuration
PORT=3000
API_KEY=replace-with-a-strong-key
[email protected],[email protected]

Environment variables table

Variable	Purpose
SMTP_HOST	SMTP server hostname
SMTP_PORT	SMTP server port
SMTP_USER	SMTP username
SMTP_PASS	SMTP password
SMTP_SECURE	Use TLS on connect (true/false)
FROM_ADDRESS	Default From: address used for outgoing mail
PORT	HTTP port the MCP server listens on
API_KEY	Simple API key used to authenticate agent requests
ALLOWED_RECIPIENTS	Comma-separated list of permitted recipient addresses

Run the server locally:

npm start
# or, if using node directly
node index.js

Docker

A minimal Docker run example (build image first):

docker build -t email-mcp-server .
docker run -e SMTP_HOST=smtp.example.com \
  -e SMTP_PORT=587 \
  -e [email protected] \
  -e SMTP_PASS=supersecretpassword \
  -e [email protected] \
  -e API_KEY=replace-with-a-strong-key \
  -p 3000:3000 \
  email-mcp-server

Available Tools / API

The MCP server exposes an HTTP JSON endpoint that implements an email “tool” for agents. Example endpoint and payload:

POST /mcp/send-email Headers:

Authorization: Bearer <API_KEY>

Request body (JSON):

{
  "to": ["[email protected]"],
  "subject": "Analysis results",
  "body": {
    "text": "Hi,\nPlease find the attached report.",
    "html": "<p>Hi,</p><p>Please find the attached report.</p>"
  },
  "attachments": [
    {
      "filename": "report.csv",
      "content_type": "text/csv",
      "content_base64": "Q29sMSxDb2wxL... (base64-encoded bytes)"
    }
  ],
  "metadata": {
    "agent_id": "agent-123",
    "context": "daily-report"
  }
}

Response (JSON):

{
  "status": "sent",
  "message_id": "[email protected]>",
  "recipients": ["[email protected]"]
}

Supported attachment modes:

content_base64 — inline base64 file payload
url — (optional) an HTTP(S) URL that the server will fetch and attach (ensure outbound access)

Validation:

Requests must include a valid API key
Recipients are validated against ALLOWED_RECIPIENTS (if configured)
Attachments are size-limited based on server settings

Use Cases

Agent delivers analysis reports to stakeholders
- An analytics agent runs a daily job, generates a CSV report, and calls the MCP endpoint with the report attached. The server sends the email and logs the event for audit.
Sharing model outputs or artifacts
- A multimodal agent produces image outputs or model checkpoints and needs to share them with a human reviewer. The agent encodes files in base64 and invokes the server to email them.
Alerts and notifications with context
- A monitoring agent detects an anomaly and sends an email with logs attached. The email includes metadata (agent_id, run_id) for tracing and triage.
Secure file handoff via controlled gateway
- Instead of giving agents SMTP credentials, you restrict outgoing emails through this MCP server, enforcing recipient whitelists and rate limits to reduce abuse.

Security and Operational Notes

Never embed SMTP credentials into distributed agents; use the MCP server as the sole SMTP client.
Protect the MCP endpoint with a strong API key or integrate with an authentication service.
Enable TLS (SMTP_SECURE=true) when supported by the mail provider.
Enforce attachment size limits and validate content types to avoid abuse.
Enable logging and monitor sending rates; add rate limiting if exposing the server to many agents.

Links

Source code and issues: https://github.com/egyptianego17/email-mcp-server

This server is designed to be a straightforward, auditable gateway for agent-driven email and file delivery. Extend or integrate it as needed to fit your deployment, security, and compliance requirements.

SMTP Email MCP Server with File Attachments