Gmail MCP Server
MCP Server for interacting with Gmail via IMAP and SMTP
Installation
npx gmail-mcp-serverAsk AI about Gmail MCP Server
Powered by Claude Β· Grounded in docs
I know everything about Gmail MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Gmail MCP Server
This project implements a Model Context Protocol (MCP) server that allows interaction with Gmail accounts via IMAP and SMTP. It provides tools for searching emails, retrieving content, managing labels (creating, deleting, renaming, applying, removing), and sending/forwarding emails.
Features
- Email Search: Search emails by date range, keyword, or raw Gmail query string. Supports searching specific folders (inbox, sent) and limiting results. Uses Gmail's
X-GM-RAWextension for efficient inbox searching (e.g., filtering bycategory:primary). - Email Content Retrieval: Fetch the full content (headers, body, attachments) of a specific email using its sequence ID.
- Label Management (CRUD):
- List all available Gmail labels (folders).
- Create new custom labels.
- Rename existing custom labels.
- Delete existing custom labels (cannot delete system labels).
- Apply labels to individual emails.
- Remove labels from individual emails.
- Batch Operations:
- Apply labels to multiple emails simultaneously using sequence IDs.
- Remove labels from multiple emails simultaneously.
- Move multiple emails to a specific label/folder.
- Email Sending: Send new emails (requires SMTP configuration).
- Email Forwarding: Forward existing emails, including attachments (requires SMTP configuration).
- Daily Email Count: Count emails received per day within a specified date range.
Project Structure
.
βββ .gitignore # Specifies intentionally untracked files that Git should ignore
βββ .python-version # Specifies Python version (used by pyenv)
βββ LICENSE # Project license file
βββ pyproject.toml # Python project configuration (dependencies, build system)
βββ README.md # This file
βββ task_list.md # Tracks development progress
βββ uv.lock # Lock file for uv package manager
βββ src/
β βββ email_client/
β βββ __init__.py
β βββ config.py # Handles loading configuration from environment variables (.env)
β βββ handlers.py # Implements the logic for handling MCP tool calls
β βββ imap_client.py # Contains functions for interacting with IMAP server
β βββ server.py # Main MCP server script using @modelcontextprotocol/sdk
β βββ smtp_client.py # Contains functions for interacting with SMTP server
β βββ tool_definitions.py # Defines the available MCP tools and their schemas
β βββ utils.py # Utility functions (e.g., email parsing, date formatting)
βββ ... (other potential files like test scripts, helper scripts)
Setup
-
Clone the repository (if applicable):
git clone https://github.com/david-strejc/gmail-mcp-server.git cd gmail-mcp-server -
Install Dependencies: This project uses
uvfor package management.# Ensure uv is installed (e.g., pip install uv) uv venv # Create virtual environment (.venv) uv sync # Install dependencies from pyproject.toml and uv.lock source .venv/bin/activate # Activate the virtual environment(Alternatively, if not using
uv, create a virtual environment and install usingpip install -r requirements.txtif arequirements.txtis generated). -
Configure Environment Variables: Create a
.envfile in the project root directory and add your Gmail credentials and server settings:# .env file GMAIL_EMAIL=your_email@gmail.com GMAIL_PASSWORD=your_app_password # Use an App Password if 2FA is enabled GMAIL_IMAP_SERVER=imap.gmail.com GMAIL_SMTP_SERVER=smtp.gmail.com GMAIL_SMTP_PORT=587 # Or 465 for SSL- Important: For Gmail, if you have 2-Factor Authentication enabled, you must generate and use an "App Password". Standard passwords will not work. See Google's documentation on App Passwords.
- Ensure "Less secure app access" is enabled if you are not using 2FA (this is generally discouraged).
Running the MCP Server
Activate the virtual environment and run the server script:
source .venv/bin/activate
python src/email_client/server.py
The server will start and listen for MCP requests via standard input/output.
Integrating with an MCP Client (e.g., Cline)
Add the server configuration to your MCP client's settings file (e.g., cline_mcp_settings.json or claude_desktop_config.json).
Example cline_mcp_settings.json entry:
{
"mcpServers": {
"gmail": {
"command": "/path/to/your/project/gmail-mcp-server/.venv/bin/python",
"args": ["/path/to/your/project/gmail-mcp-server/src/email_client/server.py"],
"env": {}, // Environment variables are loaded from .env by the script
"enabled": true, // Set to true to enable
"autoApprove": [] // Configure auto-approval if desired
}
// ... other servers
}
}
- Replace
/path/to/your/project/gmail-mcp-serverwith the actual absolute path to this project directory. - Ensure the
commandpoints to the python executable within the project's virtual environment (.venv/bin/python).
Once configured and enabled, the client should connect to the server, and the defined tools will become available.
Available Tools (Summary)
search-emails: Search emails.get-email-content: Get full email details.count-daily-emails: Count emails per day.list-labels: List all labels/folders.create-label: Create a new label.rename-label: Rename an existing label.delete-label: Delete a label.apply-label: Apply a label to one email.remove-label: Remove a label from one email.apply-label-batch: Apply a label to multiple emails.remove-label-batch: Remove a label from multiple emails.move-email: Move a single email to a label.move-email-batch: Move multiple emails to a label.send-email: Send a new email.forward-email: Forward an existing email.
Refer to src/email_client/tool_definitions.py for detailed input schemas for each tool.
