magic-mail-mcp

Read-only mail archive for Gmail and Yandex with a local polling worker and an MCP server.

It lets an agent:

• ingest new mail into a local archive automatically
• search archived mail locally with shared hybrid retrieval
• open full messages and threads through MCP
• deliver new-mail events to OpenClaw hooks when enabled

Runtime model

The package has two portable Node entrypoints:

• magic-mail-mcp — the polling worker / archive CLI
• magic-mail-mcp-mcp — the MCP server

By default, magic-mail-mcp-mcp auto-starts one local polling worker per config root. This keeps behavior consistent across clients without relying on launchd, systemd, or any other platform-specific supervisor.

If you want to disable worker auto-start for a specific host, set MAGIC_MAIL_MCP_AUTOSTART_WORKER=false.

Fast setup

1. Create a config:

npx -y magic-mail-mcp init-config

2. Fill in .env in the config directory.

3. Check config:

npx -y magic-mail-mcp doctor

4. Add the MCP server:

{
  "command": "npx",
  "args": ["-y", "magic-mail-mcp-mcp"]
}

What the agent gets

MCP tools:

• mail_today
• mail_list
• mail_search
• mail_message
• mail_thread

Important behavior:

• if you do not specify an account, mail_today and mail_list return top-N per mailbox
• every result includes mailbox/account context
• the service is read-only
• search is powered by magic-retrieval

Minimal config

Main settings in .env:

• DB_PATH — local SQLite archive path for message state
• RETRIEVAL_DB_PATH — optional SQLite path for retrieval storage; defaults to DB_PATH
• RETRIEVAL_LANCEDB_PATH — local LanceDB directory for vectors
• OPENAI_API_KEY — optional, enables semantic retrieval; without it the service falls back to lexical-only search
• GMAIL_ENABLED=true plus Gmail credentials
• YANDEX_ENABLED=true plus Yandex credentials
• OPENCLAW_DELIVERY_ENABLED=false if you only want MCP and no hook delivery

Relative paths are resolved from the config directory.

Useful commands

Validate config:

npx -y magic-mail-mcp doctor

Run one polling pass:

npx -y magic-mail-mcp --once

Run the worker explicitly:

npx -y magic-mail-mcp worker

Backfill archive:

npx -y magic-mail-mcp backfill --days 365

Search archive locally:

npx -y magic-mail-mcp search --query "invoice from alice"

Run the MCP server directly:

npx -y magic-mail-mcp-mcp

Worker logs

When the worker is auto-started by the MCP server, logs are written under the config root:

• logs/worker.out.log
• logs/worker.err.log

Notes

• Gmail uses read-only OAuth access
• Yandex uses read-only IMAP access
• mail and retrieval state are stored locally on disk
• the worker and MCP server are plain Node processes with no platform-specific service manager required
• the bridge does not send mail or modify messages

License

MIT