Gmail Attachment MCP Server

🚀 Gmail Attachment MCP Server

A server that provides microservices for downloading Gmail attachments via the Message Control Protocol (MCP).

🚀 Quick Start

This project implements a FastMCP server that allows you to download attachments from Gmail messages using the message ID. It connects to Gmail using IMAP to retrieve the attachments.

✨ Features

• Download attachments from Gmail messages using the message ID.
• Securely connect to Gmail's IMAP using SSL.
• Configure authentication credentials via environment variables.
• Provide a simple API interface through MCP.

📦 Prerequisites

• Python 3.7 or higher.
• uv installed.
• A Gmail account with IMAP enabled.
• A Gmail app password if two-step verification is enabled.

📦 Installation

# Clone the repository
git clone https://github.com/yourusername/gmail-attachment-mcp-server.git
cd gmail-attachment-mcp-server

# Install dependencies
uv sync

📚 Configuration

Set the following environment variables:

export GMAIL_USERNAME="your.email@gmail.com"
export GMAIL_PASSWORD="your_app_password"
export GMAIL_IMAP_SERVER="imap.gmail.com" # Optional, default is imap.gmail.com

⚠️ Important Note

For Gmail, you should use an app password instead of your regular password. Refer to Google's documentation for more information.

💻 Usage Examples

Basic Usage

Start the server

python server.py
# Or
mcp run server.py

Use the tool

The server exposes a download_attachments_tool that accepts the following parameters:

• message_id: Gmail message ID in hexadecimal format.
• download_folder: (Optional) The path to the folder where the attachments will be downloaded (default is "./attachments").

This function returns a list of strings containing the file paths of the downloaded attachments.

Use the mcp inspector tool

npx @modelcontextprotocol/inspector uv run mcp run server.py

Use geese

extensions:
  gmail-attachment-mcp-server:
    args:
      - run
      - /path to virtual env/.venv/bin/mcp
      - run
      - /path to gmail-attachment-mcp-server/server.py
    bundled: null
    cmd: uv
    description: null
    enabled: true
    env_keys:
      - GMAIL_USERNAME
      - GMAIL_PASSWORD
    envs: {}
    name: gmail-attachment-mcp-server
    timeout: 300
    type: stdio

Advanced Usage

The download_attachments_tool can be used in more complex scenarios. For example, you can integrate it into your own Python script and handle the downloaded attachments further.

from server import download_attachments_tool

message_id = "your_message_id"
download_folder = "./custom_attachments"
attachments = download_attachments_tool(message_id, download_folder)
for attachment in attachments:
    print(f"Downloaded attachment: {attachment}")

📚 Documentation

API Reference

download_attachments_tool

download_attachments_tool(message_id: str, download_folder="./attachments") -> list[str]

Download attachments from a Gmail message identified by its message ID.

Parameters:

• message_id: Gmail message ID in hexadecimal format.
• download_folder: (Optional) The path to the folder where the attachments will be downloaded (default is "./attachments").

Returns:

• A list of strings containing the file paths of the downloaded attachments.