Skip to content

Latest commit

 

History

History
343 lines (260 loc) · 11.9 KB

README.md

File metadata and controls

343 lines (260 loc) · 11.9 KB

mcp-email-server

Release Build status codecov Commit activity License smithery badge

IMAP and SMTP via MCP Server

Installation

Manual Installation

We recommend using uv to manage your environment.

Try uvx mcp-email-server@latest ui to config, and use following configuration for mcp client:

{
  "mcpServers": {
    "zerolib-email": {
      "command": "uvx",
      "args": ["mcp-email-server@latest", "stdio"]
    }
  }
}

This package is available on PyPI, so you can install it using pip install mcp-email-server

After that, configure your email server using the ui: mcp-email-server ui

Environment Variable Configuration

You can also configure the email server using environment variables, which is particularly useful for CI/CD environments like Jenkins. zerolib-email supports both UI configuration (via TOML file) and environment variables, with environment variables taking precedence.

{
  "mcpServers": {
    "zerolib-email": {
      "command": "uvx",
      "args": ["mcp-email-server@latest", "stdio"],
      "env": {
        "MCP_EMAIL_SERVER_ACCOUNT_NAME": "work",
        "MCP_EMAIL_SERVER_FULL_NAME": "John Doe",
        "MCP_EMAIL_SERVER_EMAIL_ADDRESS": "john@example.com",
        "MCP_EMAIL_SERVER_USER_NAME": "john@example.com",
        "MCP_EMAIL_SERVER_PASSWORD": "your_password",
        "MCP_EMAIL_SERVER_IMAP_HOST": "imap.gmail.com",
        "MCP_EMAIL_SERVER_IMAP_PORT": "993",
        "MCP_EMAIL_SERVER_SMTP_HOST": "smtp.gmail.com",
        "MCP_EMAIL_SERVER_SMTP_PORT": "465"
      }
    }
  }
}

Available Environment Variables

Variable Description Default Required
MCP_EMAIL_SERVER_ACCOUNT_NAME Account identifier "default" No
MCP_EMAIL_SERVER_FULL_NAME Display name Email prefix No
MCP_EMAIL_SERVER_EMAIL_ADDRESS Email address - Yes
MCP_EMAIL_SERVER_USER_NAME Login username Same as email No
MCP_EMAIL_SERVER_PASSWORD Email password - Yes
MCP_EMAIL_SERVER_IMAP_HOST IMAP server host - Yes
MCP_EMAIL_SERVER_IMAP_PORT IMAP server port 993 No
MCP_EMAIL_SERVER_IMAP_SSL Enable IMAP SSL true No
MCP_EMAIL_SERVER_SMTP_HOST SMTP server host - Yes
MCP_EMAIL_SERVER_SMTP_PORT SMTP server port 465 No
MCP_EMAIL_SERVER_SMTP_SSL Enable SMTP SSL true No
MCP_EMAIL_SERVER_SMTP_START_SSL Enable STARTTLS false No
MCP_EMAIL_SERVER_SMTP_VERIFY_SSL Verify SSL certificates (disable for self-signed) true No
MCP_EMAIL_SERVER_ENABLE_ATTACHMENT_DOWNLOAD Enable attachment download false No
MCP_EMAIL_SERVER_ENABLE_FOLDER_MANAGEMENT Enable folder management tools false No
MCP_EMAIL_SERVER_SAVE_TO_SENT Save sent emails to IMAP Sent folder true No
MCP_EMAIL_SERVER_SENT_FOLDER_NAME Custom Sent folder name (auto-detect if not set) - No

Enabling Attachment Downloads

By default, downloading email attachments is disabled for security reasons. To enable this feature, you can either:

Option 1: Environment Variable

{
  "mcpServers": {
    "zerolib-email": {
      "command": "uvx",
      "args": ["mcp-email-server@latest", "stdio"],
      "env": {
        "MCP_EMAIL_SERVER_ENABLE_ATTACHMENT_DOWNLOAD": "true"
      }
    }
  }
}

Option 2: TOML Configuration

Add enable_attachment_download = true to your TOML configuration file (~/.config/zerolib/mcp_email_server/config.toml):

enable_attachment_download = true

[[emails]]
# ... your email configuration

Once enabled, you can use the download_attachment tool to save email attachments to a specified path.

Enabling Folder Management

By default, folder management tools (list, create, delete, rename folders, and move/copy emails) are disabled for security reasons. To enable these features:

Option 1: Environment Variable

{
  "mcpServers": {
    "zerolib-email": {
      "command": "uvx",
      "args": ["mcp-email-server@latest", "stdio"],
      "env": {
        "MCP_EMAIL_SERVER_ENABLE_FOLDER_MANAGEMENT": "true"
      }
    }
  }
}

Option 2: TOML Configuration

Add enable_folder_management = true to your TOML configuration file (~/.config/zerolib/mcp_email_server/config.toml):

enable_folder_management = true

[[emails]]
# ... your email configuration

Once enabled, you can use the folder management tools: list_folders, create_folder, delete_folder, rename_folder, move_emails, and copy_emails.

Saving Sent Emails to IMAP Sent Folder

By default, sent emails are automatically saved to your IMAP Sent folder. This ensures that emails sent via the MCP server appear in your email client (Thunderbird, webmail, etc.).

The server auto-detects common Sent folder names: Sent, INBOX.Sent, Sent Items, Sent Mail, [Gmail]/Sent Mail.

To specify a custom Sent folder name (useful for providers with non-standard folder names):

Option 1: Environment Variable

{
  "mcpServers": {
    "zerolib-email": {
      "command": "uvx",
      "args": ["mcp-email-server@latest", "stdio"],
      "env": {
        "MCP_EMAIL_SERVER_SENT_FOLDER_NAME": "INBOX.Sent"
      }
    }
  }
}

Option 2: TOML Configuration

[[emails]]
account_name = "work"
save_to_sent = true
sent_folder_name = "INBOX.Sent"
# ... rest of your email configuration

To disable saving to Sent folder, set MCP_EMAIL_SERVER_SAVE_TO_SENT=false or save_to_sent = false in your TOML config.

Self-Signed Certificates (e.g., ProtonMail Bridge)

If you're using a local mail server with self-signed certificates (like ProtonMail Bridge), you'll need to disable SSL certificate verification:

{
  "mcpServers": {
    "zerolib-email": {
      "command": "uvx",
      "args": ["mcp-email-server@latest", "stdio"],
      "env": {
        "MCP_EMAIL_SERVER_SMTP_VERIFY_SSL": "false"
      }
    }
  }
}

Or in TOML configuration:

[[emails]]
account_name = "protonmail"
# ... other settings ...

[emails.outgoing]
verify_ssl = false

For separate IMAP/SMTP credentials, you can also use:

  • MCP_EMAIL_SERVER_IMAP_USER_NAME / MCP_EMAIL_SERVER_IMAP_PASSWORD
  • MCP_EMAIL_SERVER_SMTP_USER_NAME / MCP_EMAIL_SERVER_SMTP_PASSWORD

Then you can try it in Claude Desktop. If you want to intergrate it with other mcp client, run $which mcp-email-server for the path and configure it in your client like:

{
  "mcpServers": {
    "zerolib-email": {
      "command": "{{ ENTRYPOINT }}",
      "args": ["stdio"]
    }
  }
}

If docker is avaliable, you can try use docker image, but you may need to config it in your client using tools via MCP. The default config path is ~/.config/zerolib/mcp_email_server/config.toml

{
  "mcpServers": {
    "zerolib-email": {
      "command": "docker",
      "args": ["run", "-it", "ghcr.io/ai-zerolab/mcp-email-server:latest"]
    }
  }
}

Installing via Smithery

To install Email Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @ai-zerolab/mcp-email-server --client claude

Usage

Replying to Emails

To reply to an email with proper threading (so it appears in the same conversation in email clients):

  1. First, fetch the original email to get its message_id:
emails = await get_emails_content(account_name="work", email_ids=["123"])
original = emails.emails[0]
  1. Send your reply using in_reply_to and references:
await send_email(
    account_name="work",
    recipients=[original.sender],
    subject=f"Re: {original.subject}",
    body="Thank you for your email...",
    in_reply_to=original.message_id,
    references=original.message_id,
)

The in_reply_to parameter sets the In-Reply-To header, and references sets the References header. Both are used by email clients to thread conversations properly.

Managing Folders

You can list, create, delete, and rename email folders:

# List all folders
folders = await list_folders(account_name="work")
for folder in folders.folders:
    print(f"{folder.name} (flags: {folder.flags})")

# Create a new folder
await create_folder(account_name="work", folder_name="Projects/2024")

# Rename a folder
await rename_folder(account_name="work", old_name="Old Name", new_name="New Name")

# Delete a folder (must be empty on most servers)
await delete_folder(account_name="work", folder_name="Old Folder")

Moving and Copying Emails

Move or copy emails between folders:

# Move emails to a different folder
await move_emails(
    account_name="work",
    email_ids=["123", "456"],
    destination_folder="Archive",
    source_mailbox="INBOX"
)

# Copy emails (preserves original) - useful for applying labels
await copy_emails(
    account_name="work",
    email_ids=["123"],
    destination_folder="Labels/Important",
    source_mailbox="INBOX"
)

Note for Proton Mail users: Proton Mail Bridge exposes labels as folders under Labels/. Copying an email to a label folder effectively applies that label while keeping the original in place.

Development

This project is managed using uv.

Try make install to install the virtual environment and install the pre-commit hooks.

Use uv run mcp-email-server for local development.

Releasing a new version

  • Create an API Token on PyPI.
  • Add the API Token to your projects secrets with the name PYPI_TOKEN by visiting this page.
  • Create a new release on Github.
  • Create a new tag in the form *.*.*.

For more details, see here.