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-RAW extension for efficient inbox searching (e.g., filtering by category: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

1. Clone the repository (if applicable):

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

2. Install Dependencies: This project uses uv for package management.

   # Ensure uv is installed (e.g., pip install uv)