About Gmail Attachment MCP Server
Gmail Attachment MCP Server downloads attachments from Gmail via IMAP, for workflows that need to save files from messages. It retrieves attachments by message ID and returns their local paths.
Key features
- 01Download attachments by message ID
- 02Connect to Gmail over IMAP SSL
- 03Configure credentials with environment variables
- 04Return downloaded file paths
Use cases
- 01Extract attachments from a Gmail message
- 02Save attachments to a chosen folder
MCP support
It exposes `download_attachments_tool` to MCP clients, which retrieves attachments for a Gmail message ID and returns their file paths.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
We haven’t collected a package or remote endpoint for this server. Follow the instructions in the project README.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project READMEGmail Attachment MCP Server
A server that provides a microservice for downloading Gmail attachments using the Message Control Protocol (MCP).
Overview
This project implements a FastMCP server that allows you to download attachments from Gmail messages using a message ID. It uses IMAP to connect to Gmail and fetch the attachments.
Features
- Download attachments from Gmail messages using message ID
- Secure connection to Gmail using IMAP over SSL
- Environment variable configuration for credentials
- Simple API interface through MCP
Prerequisites
- Python 3.7 or higher
- uv needs to be installed
- Gmail account with IMAP enabled
- App Password for Gmail (if using 2-Step Verification)
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="[email protected]"
export GMAIL_PASSWORD="your_app_password"
export GMAIL_IMAP_SERVER="imap.gmail.com" # Optional, defaults to imap.gmail.com
Note: For Gmail, you should use an App Password instead of your regular password. See Google's documentation for more information.
Usage
Starting the server
python server.py
# or
mcp run server.py
Using the tool
The server exposes a download_attachments_tool that accepts the following parameters:
message_id: The Gmail message ID in hexadecimal formatdownload_folder: (Optional) The folder to download attachments to (defaults to "./attachments")
The function returns a list of paths to the downloaded attachment files.
using with mcp inspector
npx @modelcontextprotocol/inspector uv run mcp run server.py
using with goose
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
API Reference
download_attachments_tool
download_attachments_tool(message_id: str, download_folder="./attachments") -> list[str]
Downloads attachments from a Gmail message identified by its message ID.
Parameters:
message_id: The Gmail message ID in hexadecimal formatdownload_folder: (Optional) The folder to download attachments to (defaults to "./attachments")
Returns:
- A list of strings containing the file paths of downloaded attachments
License
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.