Mail Shadow MCP

@dryas

About Mail Shadow MCP

MCP server for structured, read-only email access. Exposes a minimal, auditable API surface — AI agents can search and read emails, but cannot send, delete, or modify your mailbox.

#mail #server #ai-agent #llm #secure

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "mail_shadow": {
      "command": "/path/to/mail-shadow-mcp",
      "args": [
        "serve",
        "--config",
        "/path/to/config.yaml"
      ]
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is Mail Shadow MCP?

Mail Shadow MCP is a Model Context Protocol (MCP) server that creates a local shadow copy of your IMAP mailboxes in a SQLite database. Instead of connecting directly to your IMAP server, AI agents query the local database through well-defined MCP tools, providing structured email access with built-in safety guarantees.

How to use Mail Shadow MCP?

Configure a config.yaml file with your IMAP account credentials, then run ./mail-shadow-mcp serve (or docker run for containerized deployments). Integrate with MCP clients (Claude Desktop, Cursor, etc.) by pointing them to the server via stdio or StreamableHTTP transport. Use the provided MCP tools like search_emails, get_thread, and download_attachments to interact with your mail.

Key features of Mail Shadow MCP

Local SQLite shadow database – no direct IMAP access for agents
Read-only mailbox – no STORE, APPEND, or EXPUNGE commands
Incremental sync – fetches only new messages since last sync
Full-text search via SQLite FTS5 index
Multi-account support – sync any number of IMAP accounts
Optional IMAP IDLE for near‑instant new‑mail notifications
Soft‑delete (IMAP MOVE to configurable trash folder)
Flexible transport: stdio, HTTP (StreamableHTTP), or SSE

Use cases of Mail Shadow MCP

AI agents answering questions about recent emails or threads
Automated inbox triage and notification summarization
Searching email bodies for specific topics or attachments
Building a read‑only, auditable email archive for AI consumption
Safe mailbox exploration without risk of accidental deletion

FAQ from Mail Shadow MCP

What happens when an agent calls `delete_mail`?

The server performs an IMAP MOVE to a configurable trash folder and removes the local database entry. No email is ever permanently deleted; it remains intact on the IMAP server in the trash folder.

What runtime dependencies does Mail Shadow MCP require?

It requires Go 1.25+ to build from source. Pre‑built Docker images for linux/amd64 and linux/arm64 are available on GitHub Container Registry.

Where does my email data live?

All synced email data is stored in a local SQLite database at the path specified in config.yaml (e.g., data/mail.db). Attachments are cached in a local directory. The AI agent never contacts the remote IMAP server directly.

What authentication and transport options are available?

For stdio transport (local clients), no extra auth is needed. For http or sse transport (remote/Docker), you must set http_bearer_token in config.yaml and include an Authorization: Bearer <token> header in every request.

Does Mail Shadow MCP support IMAP IDLE for real‑time sync?

Yes. You can list folders (e.g., INBOX) in the idle_folders configuration section. The server opens a dedicated IMAP connection for each folder and triggers an immediate sync upon EXISTS notifications, falling back to polling if IDLE is unsupported.

Frequently asked questions

What happens when an agent calls `delete_mail`?

The server performs an IMAP MOVE to a configurable trash folder and removes the local database entry. No email is ever permanently deleted; it remains intact on the IMAP server in the trash folder.

What runtime dependencies does Mail Shadow MCP require?

It requires Go 1.25+ to build from source. Pre‑built Docker images for `linux/amd64` and `linux/arm64` are available on GitHub Container Registry.

Where does my email data live?

All synced email data is stored in a local SQLite database at the path specified in `config.yaml` (e.g., `data/mail.db`). Attachments are cached in a local directory. The AI agent never contacts the remote IMAP server directly.

What authentication and transport options are available?

For `stdio` transport (local clients), no extra auth is needed. For `http` or `sse` transport (remote/Docker), you must set `http_bearer_token` in `config.yaml` and include an `Authorization: Bearer <token>` header in every request.

Does Mail Shadow MCP support IMAP IDLE for real‑time sync?

Yes. You can list folders (e.g., `INBOX`) in the `idle_folders` configuration section. The server opens a dedicated IMAP connection for each folder and triggers an immediate sync upon `EXISTS` notifications, falling back to polling if IDLE is unsupported.