Gmail MCP Server Btq

🚀 Gmail MCP Server

This project implements a Model Context Protocol (MCP) server that enables interaction with Gmail accounts via IMAP and SMTP. It offers tools for searching emails, retrieving content, managing labels (create, delete, rename, apply, remove), and sending/forwarding emails.

✨ Features

• Email Search: Search for emails by date range, keywords, or raw Gmail query strings. Support searching in specific folders (inbox, sent) and limit the number of results. Utilize Gmail's X-GM-RAW extension for efficient inbox search (e.g., filter by category:primary).
• Email Content Retrieval: Retrieve the full content (headers, body, attachments) of a specific email using the sequence ID.
• Label Management (CRUD):
  • List all available Gmail labels (folders).
  • Create new custom labels.
  • Rename existing labels.
  • Delete existing custom labels (system labels cannot be deleted).
  • Apply a label to a single email.
  • Remove a label from a single email.
• Batch Operations:
  • Apply labels to multiple emails in batch using sequence IDs.
  • Remove labels from multiple emails in batch.
  • Move multiple emails to a specific label/folder.
• Send Email: Send new emails (SMTP configuration required).
• Forward Email: Forward existing emails, including attachments (SMTP configuration required).
• Daily Email Count: Count the number of emails received each day within a specified date range.

📁 Project Structure

.
├── .gitignore         # Specify files to be ignored by Git
├── .python-version    # Specify Python version (for pyenv)
├── LICENSE            # Project license file
├── pyproject.toml     # Python project configuration (dependencies, build system)
├── README.md          # This file
├── task_list.md       # Track development progress
├── uv.lock            # Lock file for uv package manager
├── src/
│   └── email_client/
│       ├── __init__.py
│       ├── config.py        # Handle loading configuration from environment variables (.env)
│       ├── handlers.py      # Implement logic for handling MCP tool calls
│       ├── imap_client.py   # Contain functions for interacting with the IMAP server
│       ├── server.py        # Main MCP server script using @modelcontextprotocol/sdk
│       ├── smtp_client.py   # Contain functions for interacting with the SMTP server
│       └── tool_definitions.py # Define all available tools and their detailed input patterns

🚀 Quick Start

Step 1: Clone the Repository

git clone https://github.com/yourusername/gmail-mcp-server.git
cd gmail-mcp-server

Step 2: Create a Virtual Environment and Install Dependencies

python -m venv .venv
source .venv/bin/activate  # Use .venv\Scripts\activate on Windows
pip install -r requirements.txt

Step 3: Configure Environment Variables

Create a .env file and add the following content:

Gmail_IMAP_HOST=imap.gmail.com
Gmail_SMTP_HOST=smtp.gmail.com
Gmail_PORT=143  # IMAP port
Gmail_SSL_PORT=465  # SMTP SSL port
Gmail_EMAIL=your_email@gmail.com
Gmail_PASSWORD=your_app_specific_password

Step 4: Run the Server

source .venv/bin/activate  # Use .venv\Scripts\activate on Windows
python src/email_client/server.py

💻 Available Tools (Summary)

• search-emails: Search for emails.
• get-email-content: Retrieve full email details.
• count-daily-emails: Count the number of emails received each 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 a single email.
• remove-label: Remove a label from a single email.
• apply-label-batch: Apply labels to multiple emails in batch.
• remove-label-batch: Remove labels from multiple emails in batch.
• 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.

For detailed input patterns of each tool, refer to src/email_client/tool_definitions.py.