emancipation 0.2.0

MCP server that connects AI agents to IMAP

Emancipation MCP Server

emancipation is a MCP server that lets AI agents read IMAP mailboxes and send plain-text emails over SMTP.

Features

• No external dependencies besides the MCP SDK
• MCP server over stdio
• IMAP mailbox listing, search, message listing, and message retrieval
• SMTP plain-text email sending with optional cc, bcc, and reply_to
• TLS/SSL options for both IMAP and SMTP transports
• Environment-variable configuration for runtime credentials and behavior

---

Requirements

• Python 3.11+
• IMAP server credentials
• SMTP server credentials

---

Installation

pip install emancipation

---

Running the server

Transport is a positional argument and defaults to stdio.

emancipation

This starts the MCP server over stdio (same as emancipation stdio).

For SSE transport:

emancipation sse --host 127.0.0.1 --port 8143

For streamable HTTP transport:

emancipation streamable-http --host 127.0.0.1 --port 8143

Network transports (sse, streamable-http) support:

• --host (optional, default: 127.0.0.1)
• --port (optional, default: 8143)

Equivalent invocation patterns:

emancipation [stdio]
emancipation sse [--host HOST] [--port PORT]
emancipation streamable-http [--host HOST] [--port PORT]

You can register multiple entries with different credentials and SERVER_NAME values.

---

Agent Configuration

Example

Register the server in your MCP client configuration:

{
  "mcpServers": {
    "emancipation": {
      "command": "emancipation",
      "env": {
        "SERVER_NAME": "mail-primary",
        "IMAP_HOST": "imap.example.com",
        "IMAP_PORT": "993",
        "IMAP_TIMEOUT": "15",
        "IMAP_USERNAME": "[e-mail]",
        "IMAP_PASSWORD": "your-imap-password",
        "IMAP_MAILBOX": "INBOX",
        "IMAP_ENABLED": "true",
        "SMTP_HOST": "smtp.example.com",
        "SMTP_PORT": "587",
        "SMTP_USERNAME": "[e-mail]",
        "SMTP_PASSWORD": "your-smtp-password",
        "SMTP_FROM": "[e-mail]",
        "SMTP_ENABLED": "true",
        "SMTP_TIMEOUT": "15",
        "SMTP_USE_TLS": "true",
        "SMTP_USE_SSL": "false"
      }
    }
  }
}

Environment Variables

Set these environment variables to configure the server:

Global configuration:

• SERVER_NAME (optional, default: emancipation)
• SERVER_LOG_FILE (optional; when set, log output is written to this file in addition to stdout; logs are appended to the file)
• SERVER_LOG_LEVEL (optional, default: info; accepted values: debug, info, warning, error, critical)

For IMAP email access:

• IMAP_ENABLED (optional, default: true; set to false, no, or 0 to disable IMAP tool export)
• IMAP_HOST (required)
• IMAP_PORT (optional, default: 993)
• IMAP_TIMEOUT (optional, default: 15; timeout in seconds; must be greater than 0)
• IMAP_SESSION_TTL (optional, default: 120; reuse IMAP connections for this many seconds; set to 0 to disable reuse and reconnect per call)
• IMAP_USERNAME (required)
• IMAP_PASSWORD (required)
• IMAP_MAILBOX (optional, default: INBOX)

For sending emails:

• SMTP_ENABLED (optional, default: true; set to false, no, or 0 to disable SMTP tool export)
• SMTP_HOST (required)
• SMTP_PORT (optional, default: 587; 465 when SSL is enabled)
• SMTP_TIMEOUT (optional, timeout in seconds; must be greater than 0)
• SMTP_USERNAME (required)
• SMTP_PASSWORD (required)
• SMTP_FROM (required)
• SMTP_USE_TLS (optional, default: true)
• SMTP_USE_SSL (optional, default: false)

SMTP_USE_TLS and SMTP_USE_SSL cannot both be true. IMAP_ENABLED and SMTP_ENABLED accept only true, yes, 1, false, no, and 0; any other value raises a startup error.

About SERVER_NAME

SERVER_NAME sets the MCP server identity exposed to the client/LLM.

Common use cases:

• Run multiple emancipation instances at once, each with a different IMAP/SMTP account (for example: mail-primary, mail-finance, mail-support).
• Make tool provenance clearer in multi-server setups, so logs and MCP UIs show which server handled each tool call.
• Separate environments (for example: mail-staging vs mail-production) while reusing the same binary and tool set.

If omitted, the server name defaults to emancipation.

---

Available MCP tools

• emcp_list_mailboxes: list available mailboxes
• emcp_search_messages: search message IDs (mailbox, query, limit, offset)
• emcp_list_messages: list message metadata (id, subject, sender, date) using query and paging
• emcp_get_message: fetch one message by ID, with optional plain-text body and a trust assessment (trusted, confidence, reason, auth checks)
• emcp_send_email: send a plain-text email (to, subject, text_body) with optional cc, bcc, and reply_to
• emcp_delete_message: mark one message as deleted (message_id, optional mailbox, optional expunge)
• emcp_move_message: move one message to another mailbox (message_id, destination_mailbox, optional source_mailbox, optional expunge)

Message IDs returned by search/list are mailbox-scoped. Use the same mailbox when calling emcp_get_message, emcp_delete_message, or emcp_move_message.