Overview

This MCP (Model Context Protocol) server provides a simple, secure way for AI agents or other services to send email through multiple providers while attaching files from pre-authorized directories. It supports common SMTP-based providers such as Gmail, Outlook, Yahoo, 126/163, QQ and can be configured to work with other SMTP services. The server exposes a small set of MCP-compatible tools so a model or orchestrator can request email delivery and attachment retrieval without giving direct filesystem or credential access.

The main benefits are: (1) centralizing email provider configuration and credentials in one place, (2) enforcing attachment restrictions by whitelisting directories, and (3) exposing predictable API/tool definitions that an LLM or automation system can call. This makes it suitable for automations that need to send reports, invoices, logs or user notifications while keeping runtime credentials and allowed file access controlled.

Features

Send email via multiple providers: Gmail, Outlook, Yahoo, 126/163, QQ, and other SMTP services
Attach files from configured and whitelisted directories only (prevents arbitrary file access)
MCP-compatible toolset for LLMs and agent runtimes
Simple REST endpoints for programmatic use and testing
Environment-based configuration for providers and directories
Basic security measures: API key support and allowed-path checks

Installation / Configuration

Clone the repository and install dependencies (Node.js example):

git clone https://github.com/Shy2593666979/mcp-server-email.git
cd mcp-server-email
# If Node.js
npm install

Create a .env file (example) to configure server port, provider credentials and allowed directories:

# Server
PORT=3000
MCP_API_KEY=supersecretapikey

# Default SMTP (used if provider not specified)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
[email protected]
SMTP_PASS=supersecretpassword

# Allowed attachment directories (comma-separated)
ALLOWED_DIRS=/var/app/attachments,/home/app/shared

# Provider presets (optional)
GMAIL_SMTP_HOST=smtp.gmail.com
GMAIL_SMTP_PORT=587
[email protected]
GMAIL_PASS=app-password-or-oauth-token

You can also supply a JSON config that maps provider keys to SMTP settings. Example config/providers.json:

{
  "gmail": { "host": "smtp.gmail.com", "port": 587, "secure": false },
  "outlook": { "host": "smtp.office365.com", "port": 587, "secure": false },
  "qq": { "host": "smtp.qq.com", "port": 465, "secure": true }
}

Run the server:

# development
npm run start

# or with environment inline
PORT=3000 MCP_API_KEY=xxx node server.js

Available Tools / Resources

Typical MCP tools exposed by this server (tool names and parameters may vary slightly by release):

send_email
- Description: Send an email through a configured provider.
- Parameters:
  - to (string | array) — recipient(s)
  - subject (string)
  - body (string, HTML allowed)
  - provider (string, optional) — provider key (e.g., “gmail”, “outlook”)
  - attachments (array of filenames) — files to attach (must exist in allowed dirs)
list_files
- Description: List available files in one of the configured allowed directories.
- Parameters:
  - directory (string) — one of the allowed directories
  - pattern (string, optional) — filename glob or substring filter

The server exposes REST endpoints for each tool (for example: POST /tools/send_email). It also provides a simple discovery endpoint that lists available tools and their schemas to the client.

API Examples

Send an email with attachments (curl):

curl -X POST "http://localhost:3000/tools/send_email" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer supersecretapikey" \
  -d '{
    "to": ["[email protected]"],
    "subject": "Monthly Report",
    "body": "Please find the attached report.",
    "provider": "gmail",
    "attachments": ["reports/2026-04-report.pdf"]
  }'

List files in a configured directory:

curl -X POST "http://localhost:3000/tools/list_files" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer supersecretapikey" \
  -d '{"directory": "/var/app/attachments", "pattern": "2026-04"}'

Use Cases

Automated reporting: An AI-driven scheduler composes a report and calls send_email to attach a pre-generated PDF from a whitelisted /reports folder.
Customer support: A support assistant retrieves logs or transcripts from an allowed logs directory and emails them to users or internal teams without exposing the raw file system.
Notification system: Infrastructure monitoring agents attach recent log excerpts or crash dumps to alert emails sent via the configured SMTP provider.
Privacy-preserving attachments: When models need to share files, the MCP server ensures only approved directories and filenames can be attached, reducing accidental data leaks.

Security & Best Practices

Store provider credentials in environment variables or secret stores (do not commit them).
Use app-specific passwords or OAuth tokens for providers like Gmail and Outlook when possible.
Restrict ALLOWED_DIRS to the minimum set of paths required and run the server with least privilege.
Use HTTPS and strong API keys, rotate credentials periodically, and consider rate limiting if exposed publicly.
Audit and validate filenames: the server should reject path traversal attempts (../) and only serve files that reside in configured allowed directories.

Troubleshooting

Authentication errors: verify SMTP credentials and ports (587 for STARTTLS, 465 for SMTPS).
Attachment not found: confirm the file path exists under one of ALLOWED_DIRS and that the server process can read it.
Provider-specific blocks: some providers require special account settings (e.g., enabling app passwords or less-secure-app access). Use provider documentation to configure correctly.

Email MCP Server with Multi-Provider Attachment Support