# Agent Mail Gateway [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/dominikamann/agent-mail-gateway  
**GitHub Stars:** 11  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/agent-mail-gateway

## Description
Self-hosted email for AI agents: own IMAP/SMTP mailbox per key, allow lists, calendar invites.

## Tools
Capabilities this server exposes over MCP:

- **get_mailbox_info** — Own address, current date and time, allow lists, limits and the review rules/policies
- **list_messages** — Received mail, newest first; filter by unread, or search by text, sender, subject, date
- **read_message** — One message as Markdown, incl. attachments list and received invitations
- **get_attachment** — Download an attachment
- **mark_message** — Mark read/unread; move to Trash (if allowed)
- **send_message** — Send a new email (Markdown, attachments)
- **reply_message** — Reply (or reply-all) in the thread; forward with attachments
- **create_event** — Send, change and cancel invitations
- **list_events** — Own events with attendee responses
- **respond_to_invitation** — Accept, decline or tentatively accept a received invitation

## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "agent-mail-gateway": {
    "url": "http://localhost:8080/v1/messages"
  }
}
```

## Documentation

## What Agent Mail Gateway does

The Agent Mail Gateway MCP server gives an AI agent controlled access to a mailbox hosted on an existing mail server. Each configured mailbox has its own API key, and the gateway keeps the IMAP and SMTP credentials out of the agent. It can expose mail as Markdown, convert outgoing Markdown to HTML, and handle calendar invitations alongside ordinary email.

The service is intended for self-hosting, typically as one Docker container. Mail remains on the configured mail server, while the gateway stores its operational state in SQLite. Agents can connect through MCP over Streamable HTTP, use the included stdio bridge, or call the REST API.

## How the Agent Mail Gateway MCP server works

An API key maps to exactly one configured mailbox. Receive and send allow lists determine which addresses the agent can see and contact; patterns such as `*@domain` are supported. Messages from disallowed senders are hidden from the agent and are moved to Trash or retained according to configuration.

Before sending an email or calendar invitation, the gateway can run fixed checks, optional LLM review, and administrator-defined policy checks. Built-in checks cover cases such as empty content, missing attachments referenced by the message, unresolved placeholders, duplicate messages, missing subjects, and invitations in the past. Reviews can block a request or issue a warning, depending on the mailbox settings.

## Setup and configuration

Run the service with Docker Compose, then create a `config.yaml` entry for each mailbox. The entry contains the mailbox address, API key, IMAP and SMTP connection details, login credentials, and receive/send allow lists. Secrets can be supplied through `.env`; the example uses `AGENT_API_KEY` and `AGENT_MAIL_PASSWORD`.

The health endpoint runs at `/health`, and the REST API provides OpenAPI documentation at `/docs`. A mailbox can be checked with an authenticated request to `/v1/mailbox`. A dedicated mailbox per agent is recommended because messages outside the receive allow list may be moved to Trash.

## Tools and capabilities

The Agent Mail Gateway MCP server exposes tools to:

- Inspect mailbox identity, current time, limits, allow lists, and review settings.
- List received messages with unread, text, sender, subject, and date filters.
- Read messages as Markdown and inspect attachment and invitation information.
- Download attachments, mark messages read or unread, and move permitted messages to Trash.
- Send new messages, reply or reply-all, and forward messages with attachments.
- Create, update, or cancel calendar invitations; list events and attendee responses.
- Accept, decline, or tentatively accept received invitations.

It also supports signed new-mail webhooks and records sends, rejections, and deletions in an audit log. Calendar invitations are designed to update in Outlook, Gmail, and Apple Calendar.

## Limitations and notes

The gateway does not replace the underlying IMAP/SMTP server; each mailbox still requires working mail-server configuration and credentials. Access is limited by the configured allow lists and review behavior. Optional LLM review uses an OpenAI-compatible endpoint, such as a local Ollama service, and policies can be scoped to particular recipients. The material does not specify a hosted deployment option, so operation requires self-hosting.

_Full upstream README: https://allmcps.com/mcp/agent-mail-gateway/readme_