This Gmail MCP server provides a feature-rich interface to manage Gmail directly from an AI assistant via the Model Context Protocol. It exposes a Gmail-focused MCP service that supports sending emails, reading messages with metadata, labeling and filtering, drafting emails, and archiving. The server workflows are designed so an agent can perform natural-language actions such as drafting emails, retrieving threads, applying labels, creating folders (labels), and executing advanced searches using Gmail query language. To connect, configure your MCP client (e.g., Claude Desktop or MCP Inspector) to point at this Gmail MCP server and supply the required credentials file and token path. The server relies on Google Cloud OAuth 2.0 credentials to authenticate with the Gmail API and handles token refresh automatically during operation.

Prerequisites:

• Python 3.8+
• Access to Google Cloud and Gmail API credentials (OAuth 2.0 desktop app, credentials.json)
• network access to Google APIs

1. Clone the repository and navigate to the project

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

2. Set up a virtual environment and activate it

   python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate

3. Install the package in editable mode

   pip install -e .

4. Prepare Google Cloud credentials

• Follow Google Cloud Setup steps in the README to create a project, enable Gmail API, and download the credentials JSON as credentials.json
• Place the credentials file somewhere secure, e.g. ~/.gmail-mcp/credentials.json

5. Run the server (example using MCP via UV)

   Ensure the credentials path is correct for your setup

   uv run gmail --creds-file-path /absolute/path/to/credentials.json --token-path /absolute/path/to/tokens.json

6. Optional: test the server with the MCP Inspector or Claude Desktop using the provided command templates in the README.

Tips and considerations:

• Never commit credentials or tokens to version control. Use secure paths and consider environment variables for sensitive paths.
• The server uses OAuth2 with automatic token refresh; ensure the credentials.json file is kept secure and accessible by the server process.
• When creating labels or folders, remember Gmail treats folders as labels; use label-related operations to organize messages.
• If you modify credentials or tokens, restart the MCP server to ensure updated credentials are loaded.
• For testing, the MCP Inspector can execute commands directly against the server using the specified credentials and token paths.
• Ensure the OAuth consent screen includes the required Gmail scopes (modify, read, etc.) as described in the setup guide.