Gmail MCP Server

This repository contains an implementation of a Model Context Protocol (MCP) server for Gmail, built using fastmcp. This server provides a comprehensive suite of AI-accessible tools to interact seamlessly with your Gmail account.

Features

This server currently exposes the following 19 Gmail functions to your AI agents:

Email Reading & Searching:

• read_recent_emails: Fetches the most recent emails from your inbox.

• search_emails: Searches your entire inbox based on custom queries.

• read_email_content: Fetches the full content and metadata of a specific email.

Drafts Management:

• list_drafts: Lists all current drafts.

• create_draft: Creates a new email draft.

• create_response_draft: Creates a draft threaded as a reply to a specific email.

• modify_draft: Updates an existing draft's recipients, subject, or content.

• send_draft: Sends an existing draft.

Email Actions:

• delete_message: Moves an email to the trash (or permanently deletes it if already in trash).

• untrash_message: Restores an email from the trash to the inbox.

• forward_email: Forwards a specific email to a new recipient.

• unsubscribe_from_email: Uses the List-Unsubscribe headers to unsubscribe you from mailing lists automatically.

• block_sender: Automatically creates a filter to move all future emails from a specific sender to the trash.

• unblock_sender: Removes a blocking filter for a sender.

• list_blocked_senders: Returns a list of all senders currently blocked via filters.

Label Management:

• list_labels: Lists all labels in your Gmail account.

• create_label: Creates a new custom label.

• apply_label: Applies a specific label to an email.

• remove_label: Removes a label from an email (can also be used to mark emails as read).

• count_messages_in_label: Counts how many messages exist under a specific label.

• delete_label: Deletes a custom label.

Related MCP server: Gmail MCP Server

Setup

1. Create Virtual Environment & Install:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

2. Google Cloud Credentials (Required): To securely use this server, you need your own Google Cloud credentials.

   • Go to the Google Cloud Console.

   • Create a new Project and search for/enable the Gmail API.

   • Go to APIs & Services > Credentials on the left menu.

   • Click Create Credentials > OAuth client ID.

   • If prompted to configure the OAuth consent screen, set it to "Desktop app".

   • Download the resulting JSON file and rename it to credentials.json.

   • Place credentials.json directly inside this project folder. (Note: This file is ignored by Git, so it won't be uploaded!)

   • First Time Setup (Authentication): Because MCP servers run in the background, you must authorize the app manually before connecting it to an MCP client. Run the setup script in your terminal:

     python setup_auth.py

     This will open a browser window asking you to log into your Google Account and will generate a token.json file for future headless access.

3. Running the FastMCP Dev Inspector (Recommended for Testing):

   fastmcp dev inspector -m mcp_server

   This will run the server in dev mode with a UI that you can interact with from your browser!

4. Connect to an MCP Client (e.g. Claude Desktop): Add this to your MCP client configuration file:

   {
     "mcpServers": {
       "gmail": {
         "command": "/absolute/path/to/venv/bin/python",
         "args": ["/absolute/path/to/mcp_server.py"]
       }
     }
   }