Gmail MCP Server (Multi-User)

A Model Context Protocol (MCP) server for Gmail that supports many different users, each connecting their own Gmail account. Built in Python with FastMCP and FastAPI,extended with per-user account management.

Each user authenticates with their own Google App Password over standard SMTP/IMAP (no OAuth consent flow needed). Passwords are encrypted at rest and never returned by any tool or endpoint.

How multi-user works

Every registered Gmail account is a row tied to a user_id that you supply (your app's own user identifier — this server doesn't do authentication for you). All contacts, conversation threads, and messages are scoped to account_id, so different users' mailboxes never mix. One deployment can serve any number of users, each with one or more Gmail addresses connected.

Features

• Multi-user accounts: add_gmail_account / list_gmail_accounts / remove_gmail_account.
• Encrypted credentials: App passwords encrypted at rest with cryptography.Fernet.
• Database persistence: Contacts, threads, and messages stored per-account in SQLite.
• Background inbox polling: Since Gmail has no webhook push over IMAP, a background task polls every active account's inbox on an interval and imports new mail automatically.
• FastMCP Tools:
  • add_gmail_account / list_gmail_accounts / remove_gmail_account
  • send_email: Sends plain-text/HTML email with optional CC/BCC/attachments, from a specific account.
  • fetch_inbox: Polls IMAP right now for a specific account.
  • get_emails: Retrieves chronological message history with a contact.
  • search_emails: Keyword search across subject/body.
  • get_contact / list_conversations
• FastMCP Resources (Read-Only):
  • conversations://{account_id}
  • contacts://{account_id}
  • messages://{account_id}/{email}
• REST endpoints: POST/GET /accounts, DELETE /accounts/{id}, POST /accounts/{id}/fetch, GET /health.

---

Project Structure

gmail-mcp-multiuser/
├── app.py                     # Entry point (FastAPI + FastMCP mounting + poller)
├── config.py                  # Pydantic Settings env loader (server-wide only)
├── requirements.txt
│
├── mcp_server/
│   ├── server.py               # FastMCP instance
│   ├── registry.py             # Imports all tools/resources to register them
│   ├── tools/
│   │   ├── accounts.py         # add/list/remove Gmail accounts (multi-user)
│   │   ├── messages.py         # send_email, fetch_inbox, get_emails, search_emails
│   │   └── contacts.py         # get_contact, list_conversations
│   └── resources/
│       └── gmail_resources.py  # Read-only resource handlers
│
├── gmail/                       # Gmail SMTP/IMAP wrappers (fixed Gmail endpoints)
│   ├── smtp_client.py           # Sends mail per-account via SMTP
│   ├── imap_client.py           # Fetches mail per-account via IMAP
│   ├── parser.py                # Parses raw RFC822 bytes into structured data
│   └── crypto.py                # Fernet encryption for stored app passwords
│
├── services/
│   ├── account_service.py
│   ├── message_service.py
│   ├── contact_service.py
│   └── conversation_service.py
│
├── database/
│   ├── database.py
│   ├── models.py                # GmailAccount, Contact, Conversation, Message
│   └── crud.py
│
├── routes/
│   ├── accounts.py              # REST account management + manual fetch trigger
│   └── health.py
│
└── utils/
    ├── logger.py
    └── validators.py

---

Getting Started

1. Installation

cd gmail-mcp-multiuser
python -m venv .venv
# Windows:
.venv\Scripts\Activate.ps1
# macOS/Linux:
source .venv/bin/activate

pip install -r requirements.txt

2. Environment Configuration

cp .env.example .env

Generate a Fernet encryption key and put it in .env:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Fill in .env:

• ENCRYPTION_KEY: the generated Fernet key above (required — encrypts every user's stored app password).
• DATABASE_URL: defaults to local SQLite, fine for development.
• INBOX_POLL_INTERVAL_SECONDS / ENABLE_BACKGROUND_POLLING: control automatic inbox polling.

Note: there's no single Gmail account here — each user registers their own in step 4.

3. Run the server

python app.py

Exposed endpoints:

• GET http://localhost:8000/health
• POST/GET http://localhost:8000/accounts
• POST http://localhost:8000/accounts/{id}/fetch
• GET/POST http://localhost:8000/mcp/sse — FastMCP Server-Sent-Events endpoint for MCP clients

4. Register a user's Gmail account

Each user needs a Google App Password (not their normal password):

• Enable 2-Step Verification: https://myaccount.google.com/security
• Generate an App Password: https://myaccount.google.com/apppasswords

Then call the add_gmail_account MCP tool (or POST /accounts):

{
  "user_id": "user-123",
  "email": "jane@gmail.com",
  "app_password": "abcdefghijklmnop",
  "display_name": "Jane Doe"
}

This returns an account_id — use that for every subsequent send_email, fetch_inbox, get_emails, etc. call for this user.

5. Send and receive

• send_email(account_id, to, subject, body, ...) sends immediately via SMTP.
• New inbound mail is imported automatically by the background poller, or on demand via fetch_inbox(account_id) / POST /accounts/{id}/fetch.

---

Notes

• App passwords are encrypted at rest but never logged or returned by any tool/endpoint.
• Users are isolated purely by account_id scoping in the database — there is no built-in authentication layer for your application's end users; add one in front of this service if it's exposed beyond trusted internal callers.
• If fetch_inbox/send_email return an authentication error, the most common cause is using a normal Gmail password instead of an App Password, or IMAP being disabled in Gmail settings (Settings → Forwarding and POP/IMAP → Enable IMAP).