使用说明

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.

Quick Links: 🐳 Docker guide

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

Docker Installation

Run the MCP server in a Docker container:

# Build the image
docker build -t email-mcp-go:latest .

# Run in stdio mode (default)
docker run -it --rm --env-file .env email-mcp-go:latest

# Run in HTTP mode
# HTTP mode needs MCP_AUTH_TOKEN set in .env, and should stay bound to
# localhost unless it sits behind a proxy that terminates TLS.
docker run -d -p 127.0.0.1:8080:8080 --env-file .env email-mcp-go:latest ./email-mcp -http -addr 0.0.0.0:8080

Or use Docker Compose:

docker compose up

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

Using with Claude Desktop

💡 You don't need to run the server manually! Claude Desktop automatically starts and manages the MCP server. Claude Desktop launches it over stdio using the configuration below.

Quick Setup (Recommended)

Clone and configure:

git clone https://github.com/EmadMokhtar/email-mcp-go.git
cd email-mcp-go
cp .env.example .env
# Edit .env with your email credentials

Run the installer:

./install-claude.sh

Restart Claude Desktop

That's it! The email MCP server is now available in Claude. No need to run anything manually!

Manual Setup

To configure it by hand, add the email entry shown above to your claude_desktop_config.json.

Quick Manual Setup

Build the binary:

make build

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "email": {
      "command": "/absolute/path/to/email-mcp-go/bin/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"
      }
    }
  }
}

Restart Claude Desktop

Running the Server Standalone

# Using the binary
./bin/email-mcp

# Or with make
make run

# Or in development mode
make dev

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

Debugging

The Email MCP Server logs to stderr. Email content is deliberately kept out of the logs; only metadata such as folder names, message UIDs and counts is recorded. The logs cover:

Viewing logs in Claude Desktop
Running the server standalone for debugging
Understanding log messages and icons
Common error patterns and solutions

Quick Debug: Run the server standalone to see all logs:

make run
# or
./bin/email-mcp

All logs are sent to stderr and include:

🚀 Startup and initialization
🔧 Tool calls and arguments
✅ Success messages
❌ Error details

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)

Not seeing the server in Claude Desktop

Check the configuration file path is correct
Verify the binary path is absolute
Restart Claude Desktop
Check Claude Desktop logs: ~/Library/Logs/Claude/ (macOS)

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

[ ] OAuth2 support for Gmail and Microsoft
[ ] Email templates
[ ] Batch operations
[ ] Email filtering rules
[ ] Calendar integration (CalDAV)
[ ] Contact management (CardDAV)
[ ] Email scheduling
[ ] S/MIME and PGP encryption support
[ ] Webhook notifications for new emails

Made with ❤️ by Emad Mokhtar

使用说明

Email MCP Server

Features

IMAP (Reading & Managing Emails)

SMTP (Sending Emails)

Installation

Prerequisites

Install from Source

Install via Go

Docker Installation

Configuration

Environment Variables

Common Email Providers

Gmail

Outlook/Office 365

Yahoo Mail

ProtonMail Bridge

Usage

Using with Claude Desktop

Quick Setup (Recommended)

Manual Setup

Quick Manual Setup

Running the Server Standalone

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

Debugging

Common Issues

"Connection refused" or "Timeout"

"Authentication failed"

"Certificate error"

Not seeing the server in Claude Desktop

Contributing

License

Acknowledgments

Related Projects

Support

Roadmap

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器

`list_mailboxes`

`search_emails`

`get_email`

`send_email`

`reply_to_email`

`forward_email`

`mark_as_read` / `mark_as_unread`

`move_email`

`delete_email`