gmail-imap-mcp

Gmail for AI agents — App Password only. No OAuth, no Google Cloud project, no relay.

English · 简体中文

Your AI reads and sends your Gmail through plain IMAP/SMTP with a Google App Password. One config file, pip install, done. No Google Cloud console, no OAuth consent screen, no 7-day refresh-token expiry, no third-party server seeing your mail.

Ships three front-ends over one core:

Quick start

# install the release wheel (PyPI publication is pending)
pip install "gmail-imap-mcp[mcp] @ https://github.com/luojinghao6-art/gmail-imap-mcp/releases/download/v0.1.7/gmail_imap_mcp-0.1.7-py3-none-any.whl"
gmail-imap config                      # paste a Google App Password (16 chars)

Then point your AI at it — one line for any MCP client:

claude mcp add gmail -- gmail-imap-mcp

No App Password yet? Create one here — 2-Step Verification must be on first. Full details in Configure.

Related MCP server: mcp-imap

Why this exists

Most Gmail MCP servers fall into two camps, and both have a catch:

App Passwords have none of these problems. Google still supports them for personal accounts with 2-Step Verification enabled, and they are exactly what IMAP/SMTP expects.

Trade-off, stated plainly: App Passwords are being tightened over time, and they do not exist for Google Workspace accounts whose admin disabled them. IMAP also cannot edit filters, read Gmail settings, or modify an existing draft. If you need those, use a Gmail API server.

Features

• Send, reply, reply-all — HTML or plain text, multiple recipients, CC/BCC, attachments, and proper In-Reply-To / References so replies thread correctly

• Search with Gmail's own syntax via the X-GM-RAW IMAP extension: from:boss newer_than:7d, has:attachment filename:pdf, label:Work, is:unread in:anywhere — not the crippled subset of IMAP SEARCH

• Batched header fetch — one round trip per page instead of two per message (30 messages: ~25 s with the naive version, ~4 s now on a real account; the rest is TLS login plus one search round trip)

• Mailbox-safe message references — every search hit carries its mailbox and an account-wide msgid (X-GM-MSGID). UIDs are only unique inside a mailbox, so read/reply/download take the pair instead of guessing

• Attachment download and save-to-disk

• Localised folder names decoded from IMAP modified UTF-7 ([Gmail]/&XfJSIJZkkK5O9g- → [Gmail]/已删除邮件)

• SOCKS5 proxy support for networks where Gmail is blocked (GMAIL_PROXY)

• Core, CLI and Web UI are standard library only. Only the MCP server needs the mcp package

Install

# from the v0.1.7 release wheel (no PyPI account needed)
pip install "gmail-imap-mcp[mcp] @ https://github.com/luojinghao6-art/gmail-imap-mcp/releases/download/v0.1.7/gmail_imap_mcp-0.1.7-py3-none-any.whl"

# or straight from the repo
pip install "git+https://github.com/luojinghao6-art/gmail-imap-mcp.git#egg=gmail-imap-mcp[mcp]"

# CLI only, zero dependencies
pip install "gmail-imap-mcp @ https://github.com/luojinghao6-art/gmail-imap-mcp/releases/download/v0.1.7/gmail_imap_mcp-0.1.7-py3-none-any.whl"

Once the package is on PyPI, the short form works too: pip install "gmail-imap-mcp[mcp]" or uvx --from "gmail-imap-mcp[mcp]" gmail-imap-mcp.

Requires Python 3.10+ — the bundled MCP SDK does not support 3.9.

Configure

1. Create an App Password

1. Turn on 2-Step Verification: https://myaccount.google.com/security (App Passwords do not exist without it)

2. Open https://myaccount.google.com/apppasswords

3. Create one named e.g. gmail-imap, copy the 16-character password

2. Save it

gmail-imap config
# Gmail address: you@gmail.com
# App Password (16 chars, hidden): xxxx xxxx xxxx xxxx
gmail-imap status

Credentials are stored at:

• Windows — %APPDATA%\gmail-imap-mcp\credentials.json

• macOS / Linux — ~/.config/gmail-imap-mcp/credentials.json

with 0600 permissions. You can also skip the file entirely and set GMAIL_ADDRESS / GMAIL_APP_PASSWORD environment variables — useful for containerised MCP configs.

Connect it to your AI

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["--from", "gmail-imap-mcp[mcp]", "gmail-imap-mcp"],
      "env": {
        "GMAIL_ADDRESS": "you@gmail.com",
        "GMAIL_APP_PASSWORD": "xxxx xxxx xxxx xxxx"
      }
    }
  }
}

Leave out env if you already ran gmail-imap config.

Claude Code / Cursor / any MCP client

claude mcp add gmail -- uvx --from "gmail-imap-mcp[mcp]" gmail-imap-mcp

As a Claude Code skill

Copy skill/SKILL.md to ~/.claude/skills/gmail/SKILL.md. The skill drives the CLI, so the agent picks it up automatically when the user mentions email.

Web UI

gmail-imap-ui            # opens http://127.0.0.1:8765/
gmail-imap-ui --port 9000 --no-browser

Three panes: folders, message list, reading pane. Compose with attachments, reply / reply-all, Gmail-syntax search. Binds to 127.0.0.1 only and requires a per-process token, so a random website cannot drive your inbox.

Email HTML is rendered inside a sandbox iframe with a strict CSP: scripts in an email do not run, and remote images do not load (no tracking pixels). This is deliberate.

MCP tools

Pass the mailbox returned by gmail_search together with its uid. UIDs are per-mailbox; without the mailbox a read can resolve to a different message in All Mail. msgid is account-wide and never has that problem.

CLI

gmail-imap status
gmail-imap search --query "from:boss newer_than:7d" --limit 10
gmail-imap read --uid 12345 --mailbox "INBOX" --save-attachments "~/Downloads/gmail-imap"
gmail-imap read --msgid 1278455344230334865
gmail-imap send --to a@b.com --subject "Hi" --body "Hello"
gmail-imap send --to a@b.com --subject "Report" --body "See attached" --attach report.pdf --dry-run
gmail-imap labels

Add --json to search / read / labels for machine-readable output. --dry-run builds the message and prints the recipients without touching SMTP.

Security notes

• Credentials are plaintext on disk. That is the same model as ~/.netrc or ~/.aws/credentials. Restrict the file, never commit it, and revoke the App Password at Google if it leaks.

• App Passwords grant full mailbox access. They cannot be scoped down the way OAuth scopes can. Use a dedicated Google account if that matters to you.

• Email is untrusted input. A message can contain instructions aimed at your AI. server.py tells the model to treat email content as data, but prompt injection is not solvable with a sentence — review before letting an agent send mail on your behalf.

• The web UI is localhost-only and token-gated. It also rejects foreign Host headers (DNS rebinding), checks Origin/Referer on writes, requires Content-Type: application/json, and sends CSP, X-Frame-Options: DENY, nosniff and no-referrer. Do not port-forward it.

• Credentials are owner-only on disk, and that is checked. The config file is created empty, locked down, and only then filled, so the password never exists under inherited permissions. POSIX verifies the mode with stat; Windows resets the ACL — explicit and inherited ACEs alike — grants the current user (with inheritance on the config folder, so its contents stay usable), and reads the ACL back through PowerShell, which answers in ASCII so the console code page cannot corrupt the verdict. If that cannot be done the tool warns once, and with GMAIL_MCP_STRICT_PERMISSIONS=1 it refuses: gmail-imap config deletes the half-written file, and the audit write fails the send. If you would rather not keep the password in the JSON config, point GMAIL_APP_PASSWORD_FILE at a keychain export or a mounted secret.

• This is a personal connector, not a shared service. An App Password is full-mailbox access, and any process running as your OS user can read the config. One account per OS user or container; do not run it multi-tenant.

• Downloaded files are untrusted. Saving an attachment safely says nothing about what is inside it. Do not auto-open PDFs, archives or Office files that arrived by mail; if you want a scanner in the loop, see GMAIL_MCP_SCAN_CMD below.

Code-level send controls

Prompt instructions are a suggestion; these are enforced in gmail_imap_mcp.core for the MCP server, CLI and web UI alike:

Code-level download controls

Attachments come from strangers, so inbound writes are constrained as well:

Troubleshooting

Continuous live checks

.github/workflows/live.yml runs tests/test_live.py nightly against a real mailbox. Add GMAIL_ADDRESS and GMAIL_APP_PASSWORD as repository secrets and it runs; without them the step skips, so forks and pull requests never touch a mailbox. On a public repo, use a dedicated account — anyone who can push to the default branch can read Actions secrets.

Status

• 0.1.7 — closed three holes in the 0.1.6 hardening: a duplicated _harden_dir shadowed the verifying one, the Windows ACL check used locale text mode and could raise UnicodeDecodeError, and protecting a folder stripped its children's inherited ACEs.

• 0.1.6 — permission hardening is verified instead of assumed; failures warn once, or are fatal under GMAIL_MCP_STRICT_PERMISSIONS=1.

• 0.1.5 — partial delivery (PartialSendError) and unknown send state (SendStateUnknownError) are reported accurately.

• 0.1.4 — the audit intent record is written before SMTP; a post-send audit failure says "sent, do not retry".

• 0.1.3 — owner-only credentials and audit files, GMAIL_APP_PASSWORD_FILE, GMAIL_MCP_AUDIT_STRICT, the optional GMAIL_MCP_SCAN_CMD hook, and a nightly live workflow.

• 0.1.2 — inbound attachments confined to a download allowlist, security headers on attachment downloads, token redaction, opt-in live suite.

Working and dogfooded against a real personal Gmail account: search, read, attachments, send, reply, web UI. The offline suite covers IMAP FETCH/SEARCH fixtures, message construction and threading, attachment saving, UID/mailbox resolution, the send policy and audit log, permission hardening, the web token/Host/Origin/CSP, and the MCP tool schema. The real mailbox is exercised by an opt-in live suite: GMAIL_IMAP_LIVE=1 python -m unittest tests.test_live covers login, labels, search, read by uid and by msgid, attachment fetch and a dry-run send. Not covered yet: draft editing, filters, Gmail settings (IMAP cannot do these).

Issues and PRs welcome. Please open an issue before large changes.

License

MIT — see LICENSE.