MCP Email Server

A Model Context Protocol (MCP) server for handling SMTP/IMAP email operations. This server allows you to search past emails, send new emails, and manage multiple email accounts.

Features

Search Emails: Flexible search across all email fields (sender, recipient, subject, body, date range)
Send Emails: Send emails with support for text, HTML, attachments, CC, and BCC
Multi-Account Support: Manage multiple email accounts simultaneously
Local Caching: SQLite-based cache for fast email searches
Full-Text Search: Fast full-text search using SQLite FTS5
Generic IMAP/SMTP: Works with any email provider that supports IMAP/SMTP

Requirements

Go 1.23 or higher
Docker (for containerized deployment)
Email account with IMAP/SMTP access (app passwords recommended)

Configuration

Configuration is done via environment variables. You can configure either a single account or multiple accounts.

See .env.example for a complete example configuration file.

Single Account Configuration

IMAP_HOST=imap.example.com
IMAP_PORT=993
IMAP_USERNAME=user@example.com
IMAP_PASSWORD=your_app_password
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=user@example.com
SMTP_PASSWORD=your_app_password
ACCOUNT_NAME=default

Multiple Accounts Configuration

# Account 1
ACCOUNT_1_NAME=work
ACCOUNT_1_IMAP_HOST=imap.work.com
ACCOUNT_1_IMAP_PORT=993
ACCOUNT_1_IMAP_USERNAME=user@work.com
ACCOUNT_1_IMAP_PASSWORD=your_app_password
ACCOUNT_1_SMTP_HOST=smtp.work.com
ACCOUNT_1_SMTP_PORT=587
ACCOUNT_1_SMTP_USERNAME=user@work.com
ACCOUNT_1_SMTP_PASSWORD=your_app_password

# Account 2
ACCOUNT_2_NAME=personal
ACCOUNT_2_IMAP_HOST=imap.gmail.com
ACCOUNT_2_IMAP_PORT=993
ACCOUNT_2_IMAP_USERNAME=user@gmail.com
ACCOUNT_2_IMAP_PASSWORD=your_app_password
ACCOUNT_2_SMTP_HOST=smtp.gmail.com
ACCOUNT_2_SMTP_PORT=587
ACCOUNT_2_SMTP_USERNAME=user@gmail.com
ACCOUNT_2_SMTP_PASSWORD=your_app_password

Optional Configuration

CACHE_PATH=/data/email_cache.db
SEARCH_RESULT_LIMIT=100
LOG_LEVEL=info

Common Email Provider Settings

Gmail

IMAP: imap.gmail.com:993
SMTP: smtp.gmail.com:587
Note: Requires App Password (not regular password)

Outlook/Office365

IMAP: outlook.office365.com:993
SMTP: smtp.office365.com:587

Yahoo

IMAP: imap.mail.yahoo.com:993
SMTP: smtp.mail.yahoo.com:587

MCP Tools

`list_folders`

List available mailboxes/folders for configured email accounts.

Parameters:

account_name (optional): Specific account name, or all accounts if omitted

`search_emails`

Search cached emails with flexible filters.

Parameters:

account_name (optional): Filter by specific account
folder (optional): Filter by folder/mailbox
sender (optional): Filter by sender email/name
recipient (optional): Filter by recipient email
subject (optional): Filter by subject (substring match)
body (optional): Filter by body content (full-text search)
date_from (optional): Start date (ISO 8601 format)
date_to (optional): End date (ISO 8601 format)
limit (optional): Result limit (default: 100, max: 1000)

`get_email`

Retrieve full email by ID from cache or IMAP.

Parameters:

email_id (required): Email ID (from search results)
account_name (optional): Account name if needed

`send_email`

Send a new email with support for text, HTML, attachments, CC, BCC.

Parameters:

account_name (required): Account to send from
to (required): Recipient email address(es) (comma-separated)
cc (optional): CC recipients (comma-separated)
bcc (optional): BCC recipients (comma-separated)
subject (required): Email subject
body_text (optional): Plain text body
body_html (optional): HTML body
attachments (optional): Array of attachment paths/URLs
reply_to (optional): Reply-To header
in_reply_to (optional): In-Reply-To header (for replies)

Building

Local Build

go mod download
go build -o mcp-email-server ./cmd/server

Docker Build

docker build -t mcp-email-server .

Running

Local Run

./mcp-email-server

Docker Run

docker run -it --name mcp-email-container \
  -e IMAP_HOST=imap.example.com \
  -e IMAP_PORT=993 \
  -e IMAP_USERNAME=user@example.com \
  -e IMAP_PASSWORD=your_app_password \
  -e SMTP_HOST=smtp.example.com \
  -e SMTP_PORT=587 \
  -e SMTP_USERNAME=user@example.com \
  -e SMTP_PASSWORD=your_app_password \
  -v $(pwd)/data:/data \
  mcp-email-server

Alternatively, you can use an environment file:

# Copy the example file
cp .env.example .env
# Edit .env with your credentials
# Then run:
docker run -it --name mcp-email-container --env-file .env -v $(pwd)/data:/data mcp-email-server

Note: The --name flag creates a persistent container that maintains your email cache between VS Code sessions. If you need to restart the container, use docker restart mcp-email-container. To completely reset the cache, stop and remove the container with docker rm -f mcp-email-container.

MCP Configuration

To use this server with Claude Desktop or VS Code, you need to configure it in your mcp.json file.

Claude Desktop Configuration

Location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

VS Code Configuration

Location: .vscode/mcp.json in your project directory

Configuration Examples

1. Local Execution (Single Account)

Use this if you've built the server locally:

{
  "mcpServers": {
    "mcp-email": {
      "command": "/absolute/path/to/mcp-email-server",
      "env": {
        "IMAP_HOST": "imap.gmail.com",
        "IMAP_PORT": "993",
        "IMAP_USERNAME": "your-email@gmail.com",
        "IMAP_PASSWORD": "your-app-password",
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_USERNAME": "your-email@gmail.com",
        "SMTP_PASSWORD": "your-app-password",
        "CACHE_PATH": "/tmp/email_cache.db",
        "SEARCH_RESULT_LIMIT": "100",
        "LOG_LEVEL": "info"
      }
    }
  }
}

See mcp.json.example.local for a complete example.

2. Docker Execution (Single Account)

Use this to run the server in a Docker container:

{
  "mcpServers": {
    "mcp-email": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--name", "mcp-email-container",
        "-v", "/tmp:/data",
        "-e", "IMAP_HOST=imap.gmail.com",
        "-e", "IMAP_PORT=993",
        "-e", "IMAP_USERNAME=your-email@gmail.com",
        "-e", "IMAP_PASSWORD=your-app-password",
        "-e", "SMTP_HOST=smtp.gmail.com",
        "-e", "SMTP_PORT=587",
        "-e", "SMTP_USERNAME=your-email@gmail.com",
        "-e", "SMTP_PASSWORD=your-app-password",
        "-e", "CACHE_PATH=/data/email_cache.db",
        "-e", "SEARCH_RESULT_LIMIT=100",
        "-e", "LOG_LEVEL=info",
        "mcp-email-server:latest"
      ]
    }
  }
}

See mcp.json.example.docker for a complete example.

Note: Make sure you've built the Docker image first:

docker build -t mcp-email-server:latest .

3. Multi-Account Configuration

For multiple email accounts, use the ACCOUNT_N_* environment variables:

{
  "mcpServers": {
    "mcp-email": {
      "command": "/absolute/path/to/mcp-email-server",
      "env": {
        "ACCOUNT_1_NAME": "work",
        "ACCOUNT_1_IMAP_HOST": "imap.work.com",
        "ACCOUNT_1_IMAP_PORT": "993",
        "ACCOUNT_1_IMAP_USERNAME": "user@work.com",
        "ACCOUNT_1_IMAP_PASSWORD": "your-app-password",
        "ACCOUNT_1_SMTP_HOST": "smtp.work.com",
        "ACCOUNT_1_SMTP_PORT": "587",
        "ACCOUNT_1_SMTP_USERNAME": "user@work.com",
        "ACCOUNT_1_SMTP_PASSWORD": "your-app-password",
        "ACCOUNT_2_NAME": "personal",
        "ACCOUNT_2_IMAP_HOST": "imap.gmail.com",
        "ACCOUNT_2_IMAP_PORT": "993",
        "ACCOUNT_2_IMAP_USERNAME": "user@gmail.com",
        "ACCOUNT_2_IMAP_PASSWORD": "your-app-password",
        "ACCOUNT_2_SMTP_HOST": "smtp.gmail.com",
        "ACCOUNT_2_SMTP_PORT": "587",
        "ACCOUNT_2_SMTP_USERNAME": "user@gmail.com",
        "ACCOUNT_2_SMTP_PASSWORD": "your-app-password",
        "CACHE_PATH": "/tmp/email_cache.db",
        "SEARCH_RESULT_LIMIT": "100",
        "LOG_LEVEL": "info"
      }
    }
  }
}

See mcp.json.example.multi-account for a complete example.

Example Files

mcp.json.example.local - Local execution with single account
mcp.json.example.docker - Docker execution with single account (env vars in args)
mcp.json.example.docker-envfile - Docker execution using an env file
mcp.json.example.multi-account - Local execution with multiple accounts

Using Docker with Environment File

For a cleaner Docker configuration, you can use an environment file:

{
  "mcpServers": {
    "mcp-email": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--name", "mcp-email-container",
        "--env-file", "/absolute/path/to/.env",
        "-v", "/tmp:/data",
        "mcp-email-server:latest"
      ]
    }
  }
}

See mcp.json.example.docker-envfile for a complete example.

This approach keeps your credentials in a separate .env file (which should not be committed to version control).

Setup Instructions

Choose your configuration (local or Docker)
Copy the appropriate example file to your MCP config location
Update the paths and credentials with your actual values
Restart Claude Desktop or VS Code to load the configuration

Security Notes

Never commit your actual mcp.json with real passwords to version control
Use app passwords instead of your regular email password
Consider using environment variables or secrets management for production

Development

Project Structure

mcp-email/
├── cmd/server/          # Main application entry point
├── internal/
│   ├── config/          # Configuration management
│   ├── email/           # IMAP/SMTP client implementations
│   ├── cache/           # SQLite cache layer
│   ├── mcp/             # MCP server implementation
│   └── tools/           # MCP tool implementations
├── pkg/types/           # Shared data types
└── Dockerfile           # Docker container definition

Testing

go test ./...

Linting

golangci-lint run --timeout=5m

CI/CD

This project uses GitHub Actions for continuous integration and releases.

CI Workflow

Runs on every push and pull request
Tests on multiple Go versions (1.21, 1.22, 1.23)
Runs linters and code quality checks
Builds and validates on multiple platforms
Builds and tests Docker image

Release Workflow

Automatically triggered on version tags (e.g., v1.0.0)
Validates semantic versioning (must be greater than previous tag)
Builds binaries for all platforms (Linux, macOS, Windows - amd64, arm64)
Publishes Docker images to GitHub Container Registry (and optionally Docker Hub)
Creates GitHub releases with all artifacts

Creating a Release

Create and push a version tag:

git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

The release workflow will automatically:
- Validate the version
- Build all binaries
- Create Docker images
- Publish to registries
- Create GitHub release

See RELEASE.md and .github/SETUP.md for detailed information.

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github		.github
cmd/server		cmd/server
internal		internal
pkg/types		pkg/types
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.golangci.yml		.golangci.yml
Dockerfile		Dockerfile
README.md		README.md
RELEASE.md		RELEASE.md
go.mod		go.mod
go.sum		go.sum
server.pid		server.pid
server.yaml		server.yaml
tools.json		tools.json

MorphStack/mcp-email

Folders and files

Latest commit

History

Repository files navigation

MCP Email Server

Features

Requirements

Configuration

Single Account Configuration

Multiple Accounts Configuration

Optional Configuration

Common Email Provider Settings

Gmail

Outlook/Office365

Yahoo

MCP Tools

list_folders

search_emails

get_email

send_email

Building

Local Build

Docker Build

Running

Local Run

Docker Run

MCP Configuration

Claude Desktop Configuration

VS Code Configuration

Configuration Examples

1. Local Execution (Single Account)

2. Docker Execution (Single Account)

3. Multi-Account Configuration

Example Files

Using Docker with Environment File

Setup Instructions

Security Notes

Development

Project Structure

Testing

Linting

CI/CD

CI Workflow

Release Workflow

Creating a Release

License

Contributing

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`list_folders`

`search_emails`

`get_email`

`send_email`

Packages