Gmail MCP

Private multi-account Gmail MCP server for Codex.

Development

Open this repository through Remote SSH and choose Dev Containers: Reopen in Container. The container exposes only this repository, runs as the unprivileged vscode user, and uses a repository-specific Codex home on the VM. Its sole Docker security override relaxes seccomp because the real Codex workspace sandbox was verified to require nested user namespaces on this VM. No capabilities, privileged mode, AppArmor override, or Docker socket are used.

The central development image provides Python, uv, Codex, and generic build tools. Project dependencies are installed from the checked-in uv.lock into this repository's ignored .venv. The devcontainer creates that environment automatically and keeps it isolated from every other repository and worktree.

The project commands are:

uv lock --check
uv sync --frozen --group dev
uv run --frozen pytest
uv run --frozen flake8 src tests
uv build

The first time this repository is opened, authenticate its isolated Codex state with the primary development ChatGPT account by running codex login in the container. Do not put API keys in the devcontainer configuration.

Quick Start

1. Create a Google Cloud project, enable the Gmail API, and create a Web Application OAuth client.
2. Register http://localhost:8080/admin/oauth/callback or your LAN hostname equivalent as an authorized redirect URI.
3. Generate secrets:

uv run --frozen python - <<'PY'
from cryptography.fernet import Fernet
import secrets
print("GMAIL_MCP_ENCRYPTION_KEY=" + Fernet.generate_key().decode())
print("ADMIN_TOKEN=" + secrets.token_urlsafe(32))
print("MCP_BEARER_TOKEN=" + secrets.token_urlsafe(32))
PY

4. Save the generated values and Google credentials in ~/.config/dev-secrets/gmail_mcp.env on the VM, then set mode 0600.

5. Start the server with command-scoped secret injection:

./scripts/dev-compose up --build

6. Add accounts through the admin OAuth flow:

http://localhost:8080/admin/oauth/start?alias=personal&token=<ADMIN_TOKEN>

7. Connect Codex:

export MCP_BEARER_TOKEN="<same token>"
codex mcp add gmail --url http://localhost:8080/mcp --bearer-token-env-var MCP_BEARER_TOKEN

Required Environment

• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• GOOGLE_REDIRECT_URI
• GMAIL_MCP_ENCRYPTION_KEY
• ADMIN_TOKEN
• MCP_BEARER_TOKEN

Optional:

• DATABASE_URL, default sqlite:////data/gmail_mcp.sqlite3
• MCP_ALLOWED_HOSTS, comma-separated, default localhost,localhost:*,127.0.0.1,127.0.0.1:*
• MCP_ALLOWED_ORIGINS, comma-separated, default empty
• LOG_LEVEL, default INFO

Safety Model

Draft creation happens immediately. Sending mail, sending drafts, label changes, archive, mark read/unread, star/unstar, and trash create pending actions first. A caller must execute gmail_pending_action_confirm with the returned pending_action_id before Gmail state changes.

The committed .env.example is a variable-name contract only. Real values stay outside Git and are passed to Docker Compose only for the command being run.