gmail

This Gmail MCP Server exposes a set of MCP tools that let you interact with a Gmail account via IMAP and SMTP. You can search emails, fetch full content (headers, body, attachments), manage labels (folders), send new messages, and forward existing messages. You’ll find tools such as search-emails for filtering by date, keywords, or Gmail query strings; get-email-content to retrieve full details of a message; and label-management tools to create, rename, delete, and apply labels to individual or multiple messages. There are batch tools for applying/removing labels across multiple messages and moving messages between labels. For email sending and forwarding, the server uses SMTP settings you provide. The server also includes a daily count capability to tally emails received in a date range. To use it, run the server script locally, then configure your MCP client to connect to it and enable the list of available tools. Each tool has a defined input schema in the tool definitions, so the client can validate the required fields before sending a request.

Prerequisites:

• Python 3.8+ (or compatible Python version in your environment)
• Git
• Access to Gmail account you want to manage (with App Passwords if 2FA is enabled)

Installation steps:

1. Clone the repository git clone https://github.com/david-strejc/gmail-mcp-server.git cd gmail-mcp-server

2. Create and activate a virtual environment python -m venv .venv source .venv/bin/activate # macOS/Linux .venv\Scripts\activate # Windows

3. Install dependencies

   • If the project provides a requirements file: pip install -r requirements.txt
   • If using pyproject.toml with poetry/uv, install dependencies per your workflow (see notes below).

4. Configure environment variables Create a .env file in the project root with Gmail credentials and server settings, for example: GMAIL_EMAIL=your_email@gmail.com GMAIL_PASSWORD=your_app_password GMAIL_IMAP_SERVER=imap.gmail.com GMAIL_SMTP_SERVER=smtp.gmail.com GMAIL_SMTP_PORT=587

5. Run the server python src/email_client/server.py

Notes:

• If you prefer using uv (as described in the project), you can install uv and manage dependencies via uv sync as shown in the project README. The essential effect is that the server script (server.py) is executed in an isolated environment with the required dependencies available.
• Ensure that Gmail allows the app to connect (App Password if 2FA is enabled, and appropriate access settings).

Environment variables are read from a .env file by the server. Make sure to keep credentials secure and do not commit .env to version control. If you encounter issues connecting to Gmail, verify that less secure app access is disabled when using modern security practices and rely on App Passwords. The available MCP tools cover common email management tasks: searching, retrieving content, labeling, moving, sending, and forwarding. For large batches, use the batch tools (apply-label-batch, remove-label-batch, move-email-batch) to optimize operations. Refer to src/email_client/tool_definitions.py for exact input schemas and validation for each tool.