# gmail-agent

> Gmail for AI agents, as a CLI (`gmail-agent ... --json`) and an MCP server over stdio (`gmail-agent mcp`). Search with Gmail query syntax, read messages and threads as plain text, list and download attachments (never overwrites, sanitized names), extract text from PDF attachments, send, reply, reply-all, forward with attachments, manage drafts and labels, mark read/starred/archived, trash, and permanently delete behind an explicit flag. Every write command has a dry run. Uses the user's own Google Cloud OAuth client; the access level (readonly, compose, modify, full) is chosen at login, default modify. Tokens stay in ~/.config/gmail-agent/.

Install: `uv tool install gmail-agent` (or run without installing: `uvx gmail-agent mcp`)
Claude Code plugin (MCP server plus a skill): `/plugin install gmail-agent --marketplace dremok/gmail-agent`. Other clients: `claude mcp add gmail --scope user -- uvx gmail-agent mcp`, `codex mcp add gmail -- uvx gmail-agent mcp`, `gemini mcp add --scope user gmail uvx gmail-agent mcp`, or `{"command": "uvx", "args": ["gmail-agent", "mcp"]}` in any mcpServers config. MCP Registry name: `io.github.dremok/gmail-agent`.
Check setup: `gmail-agent status --json` (exit 0 = ready). Setup needs the human: `gmail-agent setup [--scope readonly|compose|modify|full]` in their terminal walks them through the Google Cloud project, consent screen and Desktop OAuth client (saved to `~/.config/gmail-agent/credentials.json`) and logs in; `gmail-agent login` redoes only the login.

CLI commands: `search`, `message`, `thread`, `attachments`, `download`, `fetch`, `read`, `send`, `reply`, `forward`, `draft list|get|create|update|send|delete`, `labels`, `label list|create|rename|delete|add|remove`, `mark-read`, `mark-unread`, `star`, `unstar`, `archive`, `unarchive`, `trash`, `untrash`, `delete --permanent`, `setup`, `login`, `logout`, `status`, `mcp`. Write commands take `--dry-run`; `send`, `reply`, `forward` take `--draft`.
MCP tools: `account_status`, `search_messages`, `get_message`, `get_thread`, `list_labels`, `list_attachments`, `download_attachments`, `download_matching_attachments`, `read_attachment_text`, `list_drafts`, `get_draft`, `send_message`, `reply_to_message`, `forward_message`, `create_draft`, `update_draft`, `send_draft`, `delete_draft`, `create_label`, `rename_label`, `delete_label`, `modify_labels`, `mark_messages`, `trash`, `untrash`, and `delete_permanently` (only with `mcp --allow-delete` and a full login). The server exposes only the tools the saved login's access level allows; `mcp --read-only` keeps only the reading tools. Write tools take `dry_run`. `--json` is accepted before or after the CLI command.
Local files: over MCP, downloads and attachment_paths must be inside ~/Downloads or a folder allowed with `gmail-agent mcp --allow-dir PATH` (repeatable) or GMAIL_AGENT_ALLOWED_DIRS. Keys, credential stores, .env files, shell startup files and login items are always refused, also in the CLI.
Errors with `--json`: `{"error": "...", "code": "setup" | "scope" | "not_found" | "not_allowed" | "error"}`; exit code 2 means a setup step or scope is missing and the message names the fix.

## Docs

- [README](https://github.com/dremok/gmail-agent/blob/main/README.md): what it does, Google Cloud OAuth setup, access levels, CLI and MCP usage, security notes
- [For AI agents](https://github.com/dremok/gmail-agent/blob/main/README.md#for-ai-agents): copy-paste install, setup checks and commands
- [AGENTS.md](https://github.com/dremok/gmail-agent/blob/main/AGENTS.md): command table, rules for agents, repo layout and constraints

## Optional

- [Gmail search operators](https://support.google.com/mail/answer/7190)
- [Gmail API scopes](https://developers.google.com/workspace/gmail/api/auth/scopes)
- [Source: Gmail operations](https://github.com/dremok/gmail-agent/blob/main/src/gmail_agent/gmail.py)
- [Source: MCP server](https://github.com/dremok/gmail-agent/blob/main/src/gmail_agent/server.py)
