Gmail MCP Server: Send, Receive, Manage Emails

Overview

The Gmail MCP Server exposes Gmail functionality through a Model Context Protocol (MCP)–compatible HTTP service so applications and agents can send, receive, and organize email programmatically. It wraps Gmail’s official API behind a small MCP server layer, handling authentication, token refresh, request shaping, and common mailbox operations so your app logic can focus on message-level workflows.

This server is useful when you want a stable, authenticated interface to Gmail for bots, automation, or integrations that consume the MCP pattern. Instead of integrating directly with Gmail SDKs and managing OAuth tokens in each client, the MCP server centralizes Gmail access and exposes simple HTTP endpoints for email operations, labels, threading, and attachments.

Features

• Send and relay emails using Gmail API (raw MIME or structured JSON).
• Read messages and list mailboxes (filters, pagination, labels).
• Create, update, and delete labels to organize mail.
• Fetch message bodies and attachments.
• Centralized OAuth2 handling and credential management.
• Lightweight HTTP server compatible with MCP clients and automation.
• Configurable host, port, and Gmail scopes via environment variables.

Installation / Configuration

Clone the repository and prepare a Python environment:

git clone https://github.com/gangradeamitesh/mcp-google-email.git
cd mcp-google-email

python -m venv .venv
source .venv/bin/activate        # macOS / Linux
# .venv\Scripts\activate         # Windows PowerShell

pip install -r requirements.txt

Set up Google Cloud credentials and the Gmail API:

1. Create a Google Cloud project at https://console.cloud.google.com/.
2. Enable the Gmail API for the project.
3. Create OAuth 2.0 credentials:
   • For single-user apps: “Desktop” or “Web application” OAuth client ID → download client_secret.json.
   • For domain-wide delegation (G Suite / Workspace): create a service account and enable domain delegation.
4. Save the credential file locally (e.g., credentials.json).

Configure environment variables (example .env):

# Path to the Google OAuth client or service account JSON
GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json

# Server settings
MCP_BIND_HOST=0.0.0.0
MCP_BIND_PORT=8080

# Optional: customize Gmail scopes or impersonated user (for service accounts)
GMAIL_SCOPES=https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/gmail.send
[email protected]

Start the MCP server (example common patterns):

# If the project uses uvicorn + FastAPI
uvicorn app.main:app --host ${MCP_BIND_HOST:-0.0.0.0} --port ${MCP_BIND_PORT:-8080}

# Or if a run script is provided
python -m mcp_google_email

Check the repository README or main module to confirm the exact startup command if it differs.

Available Tools / Resources

• Repository: https://github.com/gangradeamitesh/mcp-google-email
• Gmail API docs: https://developers.google.com/gmail/api
• OAuth2 for Google APIs: https://developers.google.com/identity/protocols/oauth2
• Gmail scopes reference: https://developers.google.com/gmail/api/auth/scopes
• MCP (Model Context Protocol) concept: use server endpoints to serve model or action contexts to clients

Environment variables (quick reference):

Use Cases

1. Automated notifications
   • Use the MCP server to send transactional emails from a backend process. Example cURL to send a message (JSON is illustrative—check server API for exact shape):

curl -X POST http://localhost:8080/mcp/gmail/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "from": "[email protected]",
    "subject": "Build completed",
    "body": "Your build finished successfully."
  }'

2. Inbound message processing
   • List new messages, fetch message body, and run automated handlers (e.g., parse support requests and create tickets). Example:

# List messages in INBOX
curl "http://localhost:8080/mcp/gmail/messages?label=INBOX&maxResults=50"

# Fetch a message by ID
curl "http://localhost:8080/mcp/gmail/messages/{messageId}"

3. Mailbox organization
   • Create and assign labels programmatically for routing and retention policies:

# Create a label
curl -X POST http://localhost:8080/mcp/gmail/labels \
  -H "Content-Type: application/json" \
  -d '{"name": "support-processed", "labelListVisibility": "labelShow", "messageListVisibility": "show"}'

# Apply a label to a message
curl -X POST http://localhost:8080/mcp/gmail/messages/{messageId}/modify \
  -H "Content-Type: application/json" \
  -d '{"addLabelIds":["LABEL_ID"], "removeLabelIds":["INBOX"]}'

4. Attachment retrieval
   • Download attachments via server endpoints that proxy the Gmail attachments API, allowing your application to store or scan files.

Notes for Developers

• Review and limit Gmail scopes to the minimum required for your workflows (e.g., gmail.send, gmail.readonly, gmail.labels).
• If using a service account across a Workspace, enable domain-wide delegation and set the impersonate user variable.
• For production use, host the MCP server behind TLS and secure access (API keys, service-to-service auth, or intra-VPC networking).
• Check rate limits in Gmail API documentation and design retry/backoff behavior in clients.

This MCP server is intended to simplify Gmail integration by exposing a focused set of email operations through a single authenticated service layer. Review the repository for concrete endpoint names and sample requests; adapt configuration for credentials and deployment according to your environment.