📧 Agentic Mail MCP

A Model Context Protocol server that lets AI agents work with a Gmail account safely — read, search, summarize, and (opt-in) forward/archive/label — behind a layered safety model.

🔐 You bring your own Google app. This is a local tool, not a hosted service — you create your own OAuth client in your own Google Cloud project and authorize your own mailbox. Your credentials and token never leave your machine, and because the app only ever authorizes you, there's no central service and no Google verification to wait for.

ℹ️ Status: pre-release (0.1.0), fully functional locally. Not yet on PyPI — install from source (below).

✨ Features

🚀 Quick start

You need Python 3.11+ and a Google account. Five minutes end to end.

flowchart LR
    A[1. Install] --> B[2. Google<br/>credentials]
    B --> C[3. Configure<br/>.env]
    C --> D[4. Authorize<br/>agentic-mail-mcp auth]
    D --> E[5. Connect agent<br/>or run HTTP]

1. Install (from source until published — see Installation):

pip install "git+https://github.com/CoolDevGuys/agentic-mail-mcp.git"

2. Get Google credentials — in your Google Cloud project, enable the Gmail API, make a Desktop-app OAuth client, and download its credentials.json. Full walkthrough with the exact clicks: Getting your Google credentials 👉.

3. Configure — copy .env.example to .env and point at your downloaded file:

# Easiest: just point at the credentials.json you downloaded.
AGENTIC_MAIL_MCP_GMAIL_CLIENT_SECRETS_FILE=/path/to/credentials.json
AGENTIC_MAIL_MCP_GMAIL_TOKEN_ENCRYPTION_KEY=<any long random string>
# 🔒 Writes are denied by default. Keep read_only until you trust the setup.
AGENTIC_MAIL_MCP_RAILGUARDS_ACCESS_LEVEL=read_only

4. Authorize (one-time browser consent — stores an encrypted token):

agentic-mail-mcp auth

5. Use it — connect an AI agent over stdio or run the HTTP server. See Usage.

✅ Requirements

• 🐍 Python 3.11+
• 🔑 Your own Google OAuth credentials.json (a Desktop-app client from your Google Cloud project — how to get it)
• 🤖 (optional) an LLM API key for the digest tools (OpenAI-compatible by default)

📦 Installation

From source (works today):

pip install "git+https://github.com/CoolDevGuys/agentic-mail-mcp.git"
# or, from a clone:
pip install .

Optional extras (combine as needed, e.g. ".[postgresql,search]"):

Docker: docker compose up --build (see HTTP server).

💡 Once published to PyPI, the recommended install for MCP clients will be uvx agentic-mail-mcp / pipx run agentic-mail-mcp — no virtualenv to manage.

⚙️ Configuration

Set environment variables with the AGENTIC_MAIL_MCP_ prefix, or use a .env file (copy .env.example). The table below covers the essentials; every setting, with defaults and purpose — and the Google OAuth walkthrough — is in specs/docs/configuration.md.

🔌 Usage

The server speaks MCP over two transports:

⚠️ Authorize first. Run agentic-mail-mcp auth once (browser consent) before starting the server — it stores the encrypted token the server reads on every start. Details: Authorize.

Headless server (no browser)? auth needs a browser + loopback redirect, so you don't run it on the server. Authorize once on a machine that has a browser, then copy the encrypted token file across — see Headless / server deployment.

💻 Local (stdio) — connect an AI agent

Point your MCP client at the agentic-mail-mcp command. Example client config:

{
  "mcpServers": {
    "gmail": {
      "command": "agentic-mail-mcp",
      "env": {
        "AGENTIC_MAIL_MCP_GMAIL_OAUTH_CLIENT_ID": "...",
        "AGENTIC_MAIL_MCP_GMAIL_OAUTH_CLIENT_SECRET": "...",
        "AGENTIC_MAIL_MCP_GMAIL_TOKEN_ENCRYPTION_KEY": "...",
        "AGENTIC_MAIL_MCP_RAILGUARDS_ACCESS_LEVEL": "read_only"
      }
    }
  }
}

The agent then discovers the tools, resources, and prompts described in the MCP API reference. Start with read_only and enable read_write deliberately once you understand the railguards.

HTTP server (deployment)

Run a standalone streamable-HTTP server:

AGENTIC_MAIL_MCP_MCP_TRANSPORT=http AGENTIC_MAIL_MCP_MCP_HOST=0.0.0.0 AGENTIC_MAIL_MCP_MCP_PORT=8080 \
  agentic-mail-mcp

Or with Docker (the compose file already sets HTTP transport and a health check):

docker compose up --build           # server on http://localhost:8080

🔑 Auth on a headless host: authorize on your laptop and mount the encrypted token into the container (e.g. -v /etc/agentic-mail-mcp:/secrets:ro) — full steps under Headless / server deployment.

Point an HTTP-capable MCP client at http://<host>:8080. Keep the server behind your own auth/TLS if it's reachable beyond localhost.

🧰 MCP Tools

Full input/output schemas, resources, prompts, and error formats are in the MCP API reference.

Read Tools (always available)

• search_emails — Search emails by subject, sender, recipient, date range, labels, attachments, unread status
• get_email — Read a specific email by ID
• get_thread — Read a conversation thread
• list_unread — List unread emails
• list_labels — List labels (system, user, or all)

Write Tools (require read_write access)

• forward_email — Forward an email (recipient allowlist enforced)
• archive_email — Archive an email or thread
• delete_email — Delete an email (trash by default, archive-first policy)
• create_draft — Create a draft for review
• send_draft — Send a reviewed draft
• add_label — Add a label to an email

Intelligence — caller-first 🧠

The calling agent is itself an LLM, so per-email reasoning ships as MCP prompts the agent runs on data it fetches with get_email — no server-side inference, no added latency, no LLM key required:

• prompts: summarize_email · classify_email · draft_reply · extract_action_items

Internal LLM inference is reserved for where it pays off (map-reduce over many emails), and registers only when an LLM is configured:

• tools: daily_digest · weekly_digest
• (opt-in) set AGENTIC_MAIL_MCP_LLM_INTERNAL_TOOLS=true to also expose the per-email ones as server-side tools. See ADR 0006.

Search Tools

• semantic_search — natural-language vector search (needs the search extra)

Project Structure

agentic_mail_mcp/
  Bootstrap/           CLI, Settings, Logging, Lifespan, DI Container
  Common/              Shared domain primitives
  Gmail/               Gmail bounded context
  Intelligence/        LLM-powered email analysis
  Search/              Semantic/vector search
  Notification/        Event notifications
  MCP/                 MCP server, tools, resources, prompts
tests/
  unit/                Unit tests
  integration/         Integration tests
  fakes/               Test doubles

Railguards (security model)

Writes are denied by default. Safety is layered so an AI agent cannot mutate a mailbox unless a human deliberately enables it:

• Access level — read_only (default) or read_write. The master switch. Under read_only, write tools are not even registered with the MCP server (defense in depth), so the agent never sees them — not merely blocked at call time.
• Recipient allowlist — forwarding is restricted to configured addresses or domains (@example.com).
• Rate limits — per-action caps within a trailing 1-hour window (e.g. {"forward": 50}).
• Archive-first policy — an email must be archived before it can be permanently deleted; deletes are soft (Trash) by default.
• Draft-first sending — the agent creates a draft for human review; send_draft is a separate, explicit step.
• Audit log — every write is recorded (action, email id, correlation id).

A railguard denial surfaces to the agent as a structured permission_denied error, never as an unhandled exception. See the railguards configuration and ADR 0004.

Development

A Makefile wraps the common tasks (run make to list them):

make setup        # first-time: create .venv, install dev deps, .env, run migrations
make auth         # one-time Google authorization (browser consent)
make run          # start the server (stdio); make run-http for HTTP transport
make test         # full test suite with coverage gates (as CI runs)
make check        # lint (ruff) + type-check (mypy) + tests
make format       # auto-format and fix imports
make migrate      # apply DB migrations; make migration m="..." to autogenerate
make build        # build the sdist + wheel and validate metadata

Prefer raw tools? They work too: pytest, ruff check agentic_mail_mcp tests, mypy agentic_mail_mcp, alembic upgrade head. All make targets run inside a local .venv.

Contributing

• The architecture (DDD + vertical slicing) and key decisions are recorded as ADRs; read them before adding a bounded context or changing a boundary.
• Changes follow the OpenSpec workflow under openspec/ — propose a change, generate its spec deltas, implement, then archive.
• Keep the tiered coverage floors green (≥90% on Domain/, ≥80% overall) and ensure ruff check and mypy agentic_mail_mcp/ pass before opening a PR.

📤 Distribution

The recommended distribution is a PyPI package launched via uvx / pipx, not a compiled binary. MCP clients already know how to run command: "uvx" / "pipx run", so users get a one-line config with no virtualenv to manage, and Python-native OAuth/optional-dependency handling stays simple. A single-file binary would fight the OAuth browser flow and the optional native extras (llama.cpp, sentence-transformers, sqlite-vec) for little gain. The Docker image covers HTTP/server deployments.

Releasing (maintainers)

Releases are fully automated by the publish job in .github/workflows/ci.yml. Publishing a GitHub Release is the entire flow — it builds the sdist + wheel and uploads them to PyPI via Trusted Publishing (OIDC), so no API token is stored in the repo.

One-time PyPI setup (per project, done once in the PyPI web UI):

1. On PyPI → Publishing → add a pending trusted publisher with:
   • PyPI Project Name: agentic-mail-mcp
   • Owner: your GitHub org/user · Repository: this repo
   • Workflow name: ci.yml · Environment name: pypi
2. In GitHub → Settings → Environments → create an environment named pypi (optionally add required reviewers to gate publishes).

To cut a release:

1. Bump project.version in pyproject.toml, move the CHANGELOG.md [Unreleased] section under the new version, and merge to main.
2. On GitHub → Releases → Draft a new release → create a tag (e.g. v0.1.0) → Publish release.
3. CI runs lint / type-check / tests / audit, then the publish job builds and uploads to PyPI. Done — uvx agentic-mail-mcp now resolves the new version.

License

Released under the MIT License.