imap-mcp

A security-focused Model Context Protocol server that mediates LLM access to IMAP mailboxes under strict, auditable policy. Designed for agents that need to read, classify, move, and archive mail — but must be prevented from reading what they shouldn't, moving what they shouldn't, or leaving no trace of what they did.

Status

V1 — 241 BDD scenarios green, 0 skipped. The server is runnable on stdio and HTTP/SSE transports. Gmail (with localized folder name resolution via RFC 6154) and standard IMAP providers are supported. Optional OpenTelemetry tracing with Jaeger.

Quick start

# Install via pipx (recommended — isolated environment, global CLI)
pipx install "sc-imap-mcp[tracing]"

# Or via pip
pip install sc-imap-mcp[tracing]

# Without tracing
pipx install sc-imap-mcp

# From source
cd server && pip install -e ".[tracing]"

# Upgrade
pipx upgrade sc-imap-mcp

Configure

mkdir -p ~/.config/imap-mcp/{policies,secrets/accounts/my-account}

# Create accounts.yaml, callers.yaml, policies/*.yaml
# (see Configuration section below)

# Store your IMAP password or OAuth refresh token
echo -n 'your-password' > ~/.config/imap-mcp/secrets/accounts/my-account/password

Run on stdio (for Claude Desktop, Claude Code, Cline)

IMAP_MCP_CONFIG_DIR=~/.config/imap-mcp \
IMAP_MCP_CALLER_ID=my-agent \
  imap-mcp --transport stdio

Register with Claude Code

claude mcp add --scope user imap-mcp \
  --env IMAP_MCP_CONFIG_DIR=$HOME/.config/imap-mcp \
  --env IMAP_MCP_CALLER_ID=my-agent \
  -- imap-mcp --transport stdio

Run on HTTP (for multi-agent setups)

IMAP_MCP_CONFIG_DIR=~/.config/imap-mcp \
  imap-mcp --transport http --host 127.0.0.1 --port 8080

Architecture

┌──────────────────────────┐
│  LLM agent (MCP client)  │
└────────────┬─────────────┘
             │ MCP (stdio or HTTP/SSE)
┌────────────▼─────────────────────────────────────────┐
│  imap-mcp                                            │
│  ┌─────────────────────────────────────────────────┐ │
│  │ Policy Decision Point  — default-deny           │ │
│  │ Redaction / Transparency Layer                  │ │
│  │ Transaction Manager (WAL + saga)                │ │
│  │ IMAP Core · Batch Fetch · OAuth2 adapters       │ │
│  │ Pluggable Secret Store                          │ │
│  │ Append-only Audit Log with hash chain           │ │
│  │ OpenTelemetry Tracing (optional)                │ │
│  └─────────────────────────────────────────────────┘ │
└─────────┬───────────────────┬────────────────────────┘
          │ IMAP/IMAPS        │ IMAP/IMAPS
┌─────────▼────┐   ┌──────────▼────┐
│ Account A    │   │ Account B     │
│ (e.g. Gmail) │   │ (e.g. Dovecot)│
└──────────────┘   └───────────────┘

Configuration

The server reads its configuration from a directory of YAML files pointed to by IMAP_MCP_CONFIG_DIR.

config/
├── accounts.yaml        # IMAP accounts, secret store, audit, WAL
├── callers.yaml         # MCP callers and their auth
└── policies/
    ├── invoice-agent.yaml
    └── overview-bot.yaml

accounts.yaml

Defines every IMAP account the server may connect to, plus the secret store backend, audit log, and WAL configuration.

accounts:
  - id: company-mail
    provider: imap-standard       # or "google" for Gmail
    host: imap.example.com
    port: 993
    auth:
      type: password              # or "xoauth2"
      secret_ref: secret://accounts/company-mail/password
    token_cache: memory_only      # or "persist_all" (OAuth only)

  - id: gmail-work
    provider: google
    host: imap.gmail.com
    port: 993
    auth:
      type: xoauth2
      secret_ref: secret://accounts/gmail-work/refresh_token
      oauth_scope: https://mail.google.com/
    token_cache: persist_all

  - id: accounting@company.com
    host: imap.company.com
    port: 993
    user: mail2223                  # explicit IMAP login (when != id)
    auth:
      type: password
      secret_ref: secret://accounts/accounting@company.com/password

secret_store:
  backend: file_dir               # or "env_var" or "gpg_file"
  path: /home/user/.config/imap-mcp/secrets

audit:
  directory: /home/user/.config/imap-mcp/audit
  hot_days: 90                    # days before gzip compression
  warm_days: 275                  # additional days as .gz
  delete_after_days: 365          # total age before deletion

wal:
  path: /home/user/.config/imap-mcp/wal.db

Account fields

Secret store backends

Secret references use the format secret://path/segments. For file_dir, this resolves to {path}/path/segments.

callers.yaml

Defines every MCP caller (agent) that may connect to the server.

callers:
  - id: my-agent
    policy: my-policy
    auth:
      type: stdio_trusted

  - id: invoice-bot
    policy: invoice-policy
    auth:
      type: shared_token
      token_secret_ref: secret://callers/invoice-bot/token

Caller auth types

Caller identity is immutable for the session duration. No impersonation primitive exists.

policies/<name>.yaml

Each policy file defines what one caller may see and do.

name: my-policy
accounts:
  company-mail:
    - path: INBOX
      mode: blacklist
      default: ENVELOPE
      mark_seen: true
      rules: []

  gmail-work:
    - path: INBOX
      mode: whitelist
      default: NONE
      mark_seen: true
      move_out: true
      rules:
        - match: { from_domain: hornbach.de }
          grant: FULL
        - match: { from_domain: amazon.de }
          grant: FULL

    - path: Archive
      mode: whitelist
      default: NONE
      accept_incoming: true
      rules: []

Folder policy fields

Visibility levels

Each rule grants exactly one level from this hierarchy:

NONE < COUNT < METADATA < ENVELOPE < HEADERS < BODY < FULL

Sender rule grammar

Rules use a closed set of predicates. Predicates within one rule are AND-combined; multiple rules in a folder are OR-combined.

In whitelist mode, rules use grant: <level>. In blacklist mode, rules use cap: <level>. Mixing both in one folder is a parse-time error.

The flagged predicate matches the IMAP \Flagged flag (starred in Gmail), enabling rules like "grant full access to all starred messages":

- path: INBOX
  mode: whitelist
  default: NONE
  rules:
    - match: { flagged: true }
      grant: FULL

MCP tool surface

Nineteen tools, each gated on exactly one visibility level or one capability.

Read tools (10)

Write tools (6)

Meta tools (3)

Deliberately absent

delete, expunge, raw_imap_command, fetch_raw_rfc822, cross-account search, MCP resource subscriptions, folder CRUD, policy reload via MCP. See ADR 0018.

Environment variables

OAuth2 bootstrap

For accounts with auth.type: xoauth2 (e.g. Gmail), run the interactive bootstrap once per account to obtain the refresh token:

IMAP_MCP_CONFIG_DIR=~/.config/imap-mcp \
IMAP_MCP_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com \
IMAP_MCP_OAUTH_CLIENT_SECRET=your-client-secret \
  imap-mcp-oauth-bootstrap --account user@company.com

This prints a URL. Open it in a browser, complete the Google consent flow, then paste the redirect URL back into the terminal. On success, the refresh token is stored in the secret store. The server then exchanges it for access tokens automatically.

Setting up a GCP OAuth client

1. Go to https://console.cloud.google.com/apis/credentials
2. Create credentials > OAuth client ID > Desktop app
3. Copy the Client ID and Client Secret
4. Use them as IMAP_MCP_OAUTH_CLIENT_ID and IMAP_MCP_OAUTH_CLIENT_SECRET

Tracing (optional)

Install with tracing support and start Jaeger:

pip install sc-imap-mcp[tracing]
cd ops/tracing && docker compose up -d

# Add to your MCP server config:
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Open http://localhost:16686 for the Jaeger UI. Every MCP tool call creates a trace with nested IMAP connection and authentication spans.

Policy reload

Send SIGHUP to the running server process. The server re-parses the entire config directory, validates it, and swaps the in-memory state atomically. Parse or validation errors preserve the previous policy and write an audit record with the error.

kill -HUP $(pidof imap-mcp)

Gmail support

Accounts with provider: google get explicit Gmail semantics:

• list_labels tool available (Gmail only)
• search results include canonical_all_mail_uid for cross-label deduplication
• Intra-account move implemented as label swap (not physical MOVE)
• Cross-account sagas fetch deterministically from [Gmail]/All Mail
• [Gmail]/Trash, [Gmail]/Drafts etc. are policy-addressable folders
• Localized folder names (e.g. [Gmail]/Entwürfe in German) are resolved to canonical paths via RFC 6154 special-use flags

Audit log

Append-only JSONL with SHA-256 hash chain, one file per UTC day. Strict no-content-leak rule: no message bodies, subjects, attachment filenames, OAuth tokens, or cleartext sender addresses in DENY records.

Implementation stack

• Language: Python 3.11+
• IMAP: aioimaplib (IMAP4 and IMAP4_SSL)
• MCP: the official mcp SDK (stdio + HTTP/SSE)
• Storage: aiosqlite for WAL; YAML for config
• Validation: pydantic v2 (strict mode)
• OAuth: httpx + first-party flow implementation
• Tracing: OpenTelemetry (optional, via [tracing] extra)
• Testing: pytest (property tests) + behave (BDD, 241 scenarios)

Testing

# BDD suite (requires Docker for IMAP fixtures)
cd bdd && docker compose -f docker/docker-compose.yml up -d
.venv/bin/behave --no-color --format=progress features/

# Server property tests
cd server && .venv/bin/pytest tests/policy/ -q

Documentation

The design is captured in 23 ADRs under docs/adr/. Limitation records under docs/limitations/. Error-path analysis at docs/error_path_analysis.md.

License

GPL-3.0-or-later. See LICENSE.