Email MCP Server

A Model Context Protocol (MCP) server that provides email capabilities through IMAP and SMTP protocols. This server enables AI assistants to interact with email accounts, read messages, send emails, and manage mailboxes.

Features

IMAP (Reading & Managing Emails)

📬 List mailboxes/folders
🔍 Search emails with advanced criteria (date, sender, subject, flags)
📧 Read full email content (text, HTML, attachments)
✅ Mark emails as read/unread
📁 Move/copy emails between folders
🗑️ Delete emails
📎 Download attachments

SMTP (Sending Emails)

✉️ Send plain text and HTML emails
📎 Send emails with attachments
👥 CC and BCC support
↩️ Reply to emails
➡️ Forward emails

Installation

Prerequisites

Go 1.22 or higher
Email account with IMAP/SMTP access enabled
For Gmail: App-specific password or OAuth2 credentials

Install from Source

git clone https://github.com/EmadMokhtar/email-mcp-go.git
cd email-mcp-go
go build -o email-mcp ./cmd/email-mcp

Install via Go

go install github.com/EmadMokhtar/email-mcp-go/cmd/email-mcp@latest

Configuration

Environment Variables

Create a .env file in the project root:

cp .env.example .env

Edit the .env file with your email credentials:

# IMAP Configuration
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USERNAME=your-email@gmail.com
IMAP_PASSWORD=your-app-password
IMAP_TLS=true

# SMTP Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_TLS=true

Common Email Providers

Gmail

IMAP_HOST=imap.gmail.com
IMAP_PORT=993
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587

Note: Enable "Less secure app access" or use an App Password

Outlook/Office 365

IMAP_HOST=outlook.office365.com
IMAP_PORT=993
SMTP_HOST=smtp.office365.com
SMTP_PORT=587

Yahoo Mail

IMAP_HOST=imap.mail.yahoo.com
IMAP_PORT=993
SMTP_HOST=smtp.mail.yahoo.com
SMTP_PORT=587

ProtonMail Bridge

IMAP_HOST=127.0.0.1
IMAP_PORT=1143
SMTP_HOST=127.0.0.1
SMTP_PORT=1025
IMAP_TLS=false
SMTP_TLS=false

Usage

Running the Server

./email-mcp

Using with Claude Desktop

Add to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "email": {
      "command": "/path/to/email-mcp",
      "env": {
        "IMAP_HOST": "imap.gmail.com",
        "IMAP_PORT": "993",
        "IMAP_USERNAME": "your-email@gmail.com",
        "IMAP_PASSWORD": "your-app-password",
        "IMAP_TLS": "true",
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_USERNAME": "your-email@gmail.com",
        "SMTP_PASSWORD": "your-app-password",
        "SMTP_TLS": "true"
      }
    }
  }
}

Available Tools

`list_mailboxes`

Lists all available mailboxes/folders in the email account.

Example prompt:

Show me all my email folders

`search_emails`

Search for emails based on various criteria.

Parameters:

from - Filter by sender email
to - Filter by recipient email
subject - Filter by subject keywords
since - Emails after this date (RFC3339)
before - Emails before this date (RFC3339)
unseen - Only unread emails (boolean)
folder - Search in specific folder (default: "INBOX")
limit - Maximum number of results (default: 50)

Example prompts:

Find all unread emails from john@example.com
Show me emails from the last week about "project alpha"
Search for emails in the Sent folder from yesterday

`get_email`

Retrieve full email content by ID.

Parameters:

id - Email sequence number
folder - Mailbox name (default: "INBOX")
include_attachments - Download attachments (boolean)

Example prompt:

Show me the full content of email ID 42
Get email 123 with attachments

`send_email`

Send a new email.

Parameters:

to - Recipient email addresses (array)
subject - Email subject
body - Email body content
is_html - Send as HTML (boolean, default: false)
cc - CC recipients (optional, array)
bcc - BCC recipients (optional, array)
attachments - File attachments (optional, array)

Example prompts:

Send an email to john@example.com with subject "Meeting" and body "Let's meet tomorrow"
Compose an HTML email to team@company.com about the quarterly report

`reply_to_email`

Reply to an existing email.

Parameters:

email_id - ID of email to reply to
body - Reply message body
reply_all - Reply to all recipients (boolean, default: false)
is_html - Send as HTML (boolean, default: false)

Example prompt:

Reply to email 42 with "Thanks for the update!"
Reply all to the last email with confirmation

`forward_email`

Forward an email to other recipients.

Parameters:

email_id - ID of email to forward
to - Forward recipients (array)
message - Additional message (optional)

Example prompt:

Forward email 15 to sarah@example.com

`mark_as_read` / `mark_as_unread`

Change read status of emails.

Parameters:

email_ids - Array of email IDs
folder - Mailbox name (default: "INBOX")

Example prompts:

Mark emails 1, 2, and 3 as read
Mark email 42 as unread

`move_email`

Move email to a different folder.

Parameters:

email_id - Email ID to move
from_folder - Source folder
to_folder - Destination folder

Example prompt:

Move email 42 from INBOX to Archive

`delete_email`

Delete an email.

Parameters:

email_id - Email ID to delete
folder - Mailbox name (default: "INBOX")
permanent - Permanently delete vs move to trash (boolean)

Example prompt:

Delete email 42 permanently
Move email 15 to trash

Development

Project Structure

email-mcp-go/
├── cmd/
│   └── email-mcp/        # Main application entry point
├── internal/
│   ├── server/           # MCP server implementation
│   ├── imap/             # IMAP client and operations
│   ├── smtp/             # SMTP client and operations
│   ├── config/           # Configuration management
│   └── tools/            # MCP tool definitions
├── pkg/
│   └── models/           # Data models
├── go.mod
├── go.sum
└── README.md

Building

go build -o email-mcp ./cmd/email-mcp

Testing

go test ./...

Running in Development

go run ./cmd/email-mcp

Security Considerations

⚠️ Important Security Notes:

Credentials Storage: Never commit credentials to version control. Always use environment variables or secure credential management.
App Passwords: For Gmail and other providers, use app-specific passwords instead of your main account password.
OAuth2: Consider implementing OAuth2 for production use with Gmail and Microsoft accounts.
TLS/SSL: Always use encrypted connections (TLS) for both IMAP and SMTP.
Rate Limiting: Be mindful of email provider rate limits to avoid account suspension.
Permissions: This MCP server has full access to your email account. Only use with trusted AI assistants.

Troubleshooting

Common Issues

"Connection refused" or "Timeout"

Check firewall settings
Verify IMAP/SMTP ports are correct
Ensure TLS settings match provider requirements

"Authentication failed"

Verify username and password
For Gmail: Enable "Less secure app access" or use App Password
Check if 2FA is enabled and requires app-specific password

"Certificate error"

Update Go to the latest version
Check system certificates are up to date
For self-signed certificates, you may need to disable TLS verification (not recommended for production)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with mark3labs/mcp-go
Uses emersion/go-imap for IMAP functionality
Uses go-mail/mail for SMTP functionality
Inspired by the Model Context Protocol specification

Related Projects

MCP Servers - Official MCP server implementations
Awesome MCP Servers - Curated list of MCP servers

Support

For issues and questions:

Open an issue on GitHub
Check existing issues for solutions

Roadmap

Made with ❤️ by Emad Mokhtar

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.idea		.idea
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
go.mod		go.mod

License

EmadMokhtar/email-mcp-go

Folders and files

Latest commit

History

Repository files navigation

Email MCP Server

Features

IMAP (Reading & Managing Emails)

SMTP (Sending Emails)

Installation

Prerequisites

Install from Source

Install via Go

Configuration

Environment Variables

Common Email Providers

Gmail

Outlook/Office 365

Yahoo Mail

ProtonMail Bridge

Usage

Running the Server

Using with Claude Desktop

Available Tools

list_mailboxes

search_emails

get_email

send_email

reply_to_email

forward_email

mark_as_read / mark_as_unread

move_email

delete_email

Development

Project Structure

Building

Testing

Running in Development

Security Considerations

Troubleshooting

Common Issues

"Connection refused" or "Timeout"

"Authentication failed"

"Certificate error"

Contributing

License

Acknowledgments

Related Projects

Support

Roadmap

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

`list_mailboxes`

`search_emails`

`get_email`

`send_email`

`reply_to_email`

`forward_email`

`mark_as_read` / `mark_as_unread`

`move_email`

`delete_email`

Packages