Skip to main content
Glama
awita-mail

awita-mail

by flo-steurer

awita-mail

Secure, draft-first MCP access to a GMX business mailbox. The service uses IMAP for mailbox operations, SMTP STARTTLS for delivery, and Streamable HTTP at /mcp. Email content is always untrusted external data.

Start locally

Use Python 3.12 and a GMX application-specific password (never the normal account password). GMX defaults are imap.gmx.com:993 TLS and mail.gmx.com:587 STARTTLS.

python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
cp .env.example .env
# Edit .env: GMX_EMAIL, GMX_APP_PASSWORD, MCP_HOSTNAME, MCP_API_TOKEN
python -m app
curl -i http://127.0.0.1:8000/health

The package includes a pinned CA bundle fallback for Python installations that do not expose the macOS/system trust store (for example, a fresh python.org installation). If this virtual environment already existed before that dependency was added, run python -m pip install -e '.[dev]' again.

Generate a strong token with python -c "import secrets; print(secrets.token_urlsafe(48))". .env is Git-ignored. The MCP endpoint requires Authorization: Bearer $MCP_API_TOKEN:

curl -i -X POST http://127.0.0.1:8000/mcp \
  -H "Authorization: Bearer $MCP_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"ping"}'

Related MCP server: mcp-mail

Docker

The container exposes no host port, runs non-root, drops capabilities, and persists its SQLite audit ledger in /data.

cp .env.example .env
# Set MCP_HOSTNAME, GMX credentials, MCP_API_TOKEN, and your Traefik network.
docker compose build
docker compose up -d
docker compose ps
docker compose logs --tail=100 awita-mail

Set TRAEFIK_ENABLE=true only after DNS/TLS are ready. Keep ALLOW_SEND=false until the draft workflow is verified. Prefer GMX_APP_PASSWORD_FILE and MCP_API_TOKEN_FILE in a deployment-specific Compose secret override; never put secret contents in images, labels, or logs.

For a local Docker-only smoke test, publish only loopback with the debug override:

docker network create proxy 2>/dev/null || true
docker compose -f docker-compose.yml -f docker-compose.debug.yml up --build

Stop it with Ctrl-C; the normal Compose file remains unpublished to the host.

Test

Tests never contact GMX; mail boundaries are mocked/injectable.

. .venv/bin/activate
pytest
ruff format --check .
ruff check .
mypy app
python -m build

For interactive protocol testing, run the current MCP Inspector against http://127.0.0.1:8000/mcp with the bearer token. Call list_folders and check_gmx_connectivity first. The live folder mapping is account-specific, so do not assume English Sent/Drafts names.

Tools and sending

The tools are: list_folders, list_emails, search_emails, read_email, list_attachments, download_attachment, create_draft, create_reply_draft, update_draft, delete_draft, send_draft, mark_as_read, mark_as_unread, and check_gmx_connectivity. There is no arbitrary send, arbitrary deletion, forwarding rule, bulk operation, or move tool.

The only send workflow is read/search → create draft → user reviews → user explicitly requests send → send_draft. ALLOW_SEND=false blocks SMTP. Configure Codex write approval:

[mcp_servers.awita_mail]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "AWITA_MAIL_MCP_TOKEN"
default_tools_approval_mode = "writes"

[mcp_servers.awita_mail.tools.send_draft]
approval_mode = "prompt"

[mcp_servers.awita_mail.tools.delete_draft]
approval_mode = "prompt"

Export AWITA_MAIL_MCP_TOKEN for Codex and restart the desktop app/IDE extension. CLI alternative: codex mcp add awita_mail --url https://mcp.example.com/mcp --bearer-token-env-var AWITA_MAIL_MCP_TOKEN.

All email-derived fields are explicitly untrusted and cannot authorize a tool call. Attachment downloads are bounded inert MCP blobs; they are never executed or extracted. The durable SQLite ledger prevents successful send replay and records sanitized audit fields only.

ChatGPT later

ChatGPT custom MCP apps need a remotely reachable endpoint and supported authentication. For a private/on-premises server, use Secure MCP Tunnel. For direct public integration, replace the static bearer layer with a real OAuth/OIDC authorization server and MCP protected-resource metadata with refresh tokens. Mail logic and safeguards are already independent of authentication.

Configuration

GMX_EMAIL, GMX_APP_PASSWORD[_FILE], MCP_API_TOKEN[_FILE], MCP_HOSTNAME, MCP_PORT, MCP_BIND_HOST, ALLOW_SEND, LOG_LEVEL, IMAP_*, SMTP_*, MAIL_TIMEOUT_SECONDS, the MAX_* limits, AUDIT_DB_PATH, TRAEFIK_*, and FORWARDED_ALLOW_IPS are documented in .env.example. ALLOW_SEND defaults false; MAX_EMAIL_RESULTS is capped at 100. The service never logs credentials, Authorization headers, or full bodies.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server providing read and send access to a single IMAP/SMTP mailbox over Streamable HTTP with GitHub OAuth authentication, featuring recipient allowlists for security, email reading/searching/threading, attachments, drafts, folder management, and sending/reply tools.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to read, search, send, manage, schedule, and analyze mail across multiple IMAP/SMTP accounts, with real-time inbox watching, verification-code capture, calendar extraction, and provider-aware labeling. It also exposes drafts, templates, bulk operations, analytics, and OAuth2 support over stdio or Streamable HTTP.
      31 npm
      ISC
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to read, search, send, reply, forward, schedule, and analyze email across multiple IMAP/SMTP accounts, with drafts, templates, provider-aware labels, bulk operations, attachment handling, calendar extraction, and real-time IMAP IDLE watching. Connections are secured with TLS/STARTTLS, OAuth2 support, and rate limiting, and it can run over stdio locally or Streamable HTTP for networked access.
      31 npm
      ISC