mcp-email/README.md

MCP Email Server

A Dockerized MCP (Model Context Protocol) email assistant for law firms and legal teams.

Integrates:

• IMAP/SMTP email operations
• Shared/public folder support
• New-message tracking and flagging
• Conflict check search
• CalDAV/CardDAV (e.g., Nextcloud) for calendar and contacts
• Triage guidance using personnel/chain-of-command

Designed to be consumed by LLMs via MCP (Streamable HTTP) in Open WebUI.

Quick start

1. Build:

   docker build -t mcp-email-server /home/user/wall-o/mcp-email-server

2. Run (example):

   docker run -d
   -p 8000:8000
   -e API_KEY="your_api_key_here"
   -e LOG_LEVEL="DEBUG"
   -e IMAP_HOST=imap.example.com
   -e IMAP_PORT=993
   -e IMAP_USE_SSL=true
   -e IMAP_USERNAME="user@example.com"
   -e IMAP_PASSWORD="secret"
   -e SMTP_HOST=smtp.example.com
   -e SMTP_PORT=587
   -e SMTP_USE_TLS=true
   -e SMTP_USE_SSL=false
   -e SMTP_USERNAME="user@example.com"
   -e SMTP_PASSWORD="secret"
   -e SMTP_FROM="user@example.com"
   -e DEFAULT_CC="supervisor@example.com"
   -e BUSINESS_DESCRIPTION="A law firm handling corporate and litigation matters."
   -e PERSONNEL_JSON='[{"name":"Jane Doe","role":"Managing Partner","email":"jane@example.com","escalates_to":null},{"name":"John Smith","role":"Associate","email":"john@example.com","escalates_to":"Jane Doe"}]'
   mcp-email-server

3. Health check:

   http://localhost:8000/health

4. MCP endpoint:

   • POST http://localhost:8000/mcp
   • Uses JSON-RPC 2.0 (methods: initialize, tools/list, tools/call)

5. Integrate with Open WebUI (MCP Streamable HTTP):

   • Admin Settings → External Tools → Add Server
   • Type: MCP (Streamable HTTP)
   • Server URL: http://:8000/mcp
   • Auth: Bearer
   • Key: your_api_key_here
   • Save, then enable tools in a chat.

Environment variables

See env.example for a full list.

Core:

• API_KEY:

  • If set, all /mcp requests must include: Authorization: Bearer <API_KEY>
  • Leave empty to disable auth (not recommended in production).

• LOG_LEVEL:

  • e.g., INFO, DEBUG, ERROR (default: INFO)

IMAP (incoming mail):

• IMAP_HOST
• IMAP_PORT
• IMAP_USE_SSL
• IMAP_USERNAME
• IMAP_PASSWORD

SMTP (outgoing mail):

• SMTP_HOST
• SMTP_PORT
• SMTP_USE_TLS
• SMTP_USE_SSL
• SMTP_USERNAME
• SMTP_PASSWORD
• SMTP_FROM

Optional email:

• DEFAULT_CC: Comma-separated CC addresses.
• DEFAULT_BCC: Comma-separated BCC addresses.
• BUSINESS_DESCRIPTION: Context for the LLM (e.g., firm description).
• PERSONNEL_JSON: JSON array of personnel/chain-of-command:
  • Example: [ { "name": "Jane Doe", "role": "Managing Partner", "email": "jane@example.com", "escalates_to": null }, { "name": "John Smith", "role": "Associate", "email": "john@example.com", "escalates_to": "Jane Doe" } ]
• SCHEDULED_SEND_INTERVAL: Seconds between checks for scheduled emails (default: 10).

CalDAV/CardDAV (e.g., Nextcloud):

• DAV_BASE_URL: Base DAV URL (e.g., https://cloud.example.com/remote.php/dav)
• DAV_USERNAME
• DAV_PASSWORD
• DAV_VERIFY_TLS: true/false (default: true)

MCP tools

All tools are exposed via MCP (Streamable HTTP) at POST /mcp.

Email:

• list_folders
• search_messages
• get_new_messages
• sync_seen
• mark_as_read
• flag_message
• move_message
• copy_message
• apply_label
• remove_label
• list_labels
• get_unread_summary
• send_email
• reply_to_message
• forward_message
• save_draft
• list_attachments
• download_attachment
• search_attachments
• schedule_send
• export_conversation
• conflict_check_search
• get_triage_config

Contacts (CardDAV):

• list_carddav_addressbooks
• search_carddav_contacts
• get_carddav_contact
• create_carddav_contact
• update_carddav_contact
• delete_carddav_contact

Calendar (CalDAV):

• list_caldav_calendars
• search_caldav_events
• create_caldav_event
• update_caldav_event
• delete_caldav_event

Notes

• IMAP operations use UIDs for stability.
• Conflict check search scans subject lines across specified folders for given terms.
• New-message tracking is in-memory per container instance.
• For production:
  • Always set API_KEY.
  • Use HTTPS and secure IMAP/SMTP settings.