Gmail MCP Server
A powerful and flexible Gmail integration server built using the MCP (Message Control Protocol) framework. This server provides a robust interface to interact with Gmail APIs, offering functionality for reading, sending, and managing emails programmatically.
Features
- Read emails from multiple Gmail accounts
- Send emails with attachments
- Search emails with advanced query options
- Download email attachments
- Handle email conversations and threads
- Real-time email monitoring
- Support for multiple Gmail accounts
Prerequisites
Before running the Gmail MCP server, ensure you have the following:
- Python 3.12 or higher
- Google Cloud Project with Gmail API enabled
- OAuth 2.0 Client ID credentials
- Required Python packages (specified in pyproject.toml)
Installation
Installing via Smithery
To install Gmail Integration Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @Quantum-369/Gmail-mcp-server --client claude
- Clone the repository:
git clone <your-repository-url>
cd gmail-mcp-server
- Create and activate a virtual environment:
python -m venv venv
# On Windows
venv\Scripts\activate
# On Unix/MacOS
source venv/bin/activate
- Install dependencies:
Running on Ubuntu
- Install Python 3.12 and create a virtual environment if you haven't already:
sudo apt install python3.12 python3.12-venv -y
python3.12 -m venv venv
source venv/bin/activate
- Place your downloaded
client_secret.json in the project root. - Generate an OAuth token for the Gmail account you want to use. Copy the URL
printed by the script into a web browser and complete the sign-in process:
python gmail_token_creator.py
- Start the server:
Setup Google Cloud Project
- Go to the Google Cloud Console
- Create a new project or select an existing one
- Enable the Gmail API for your project
- Create OAuth 2.0 credentials:
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "OAuth client ID"
- Choose "Desktop app" as application type
- Download the client configuration file
- Rename the downloaded file to
client_secret.json and place it in the project root directory
Configuration
- Set up email identifiers in
gmail_token_creator.py:
email_identifier = 'your.email@gmail.com' # Change this for each account
- Run the token creator to authenticate your Gmail accounts:
python gmail_token_creator.py
The script prints an authorization URL. Copy this URL into your web browser,
complete the Google consent flow, and copy the verification code back into the
terminal if prompted. A token file will be created inside token_files/ for
future use.
- Repeat the process for each Gmail account you want to integrate
Server Structure
gmail_server.py: Main MCP server implementationgmail_api.py: Gmail API interaction functionsgoogle_apis.py: Google API authentication utilities- Supporting files:
read_emails.py: Email reading functionalitysearch_emails.py: Email search functionalitysend_emails.py: Email sending functionality
Usage
Starting the Server
Running with Docker
You can also build a container image using the provided Dockerfile:
docker build -t gmail-mcp-server .
docker run -v $(pwd)/client_secret.json:/app/client_secret.json \
-v $(pwd)/token_files:/app/token_files gmail-mcp-server
The container runs the same server and stores authentication tokens in the
token_files directory on the host so they persist between runs.
- Send Email:
await send_gmail(
email_identifier="your.email@gmail.com",
to="recipient@example.com",
subject="Test Subject",
body="Email body content",
attachment_paths=["path/to/attachment"]
)
- Search Emails:
await search_email_tool(
email_identifier="your.email@gmail.com",
query="from:someone@example.com",
max_results=30,
include_conversations=True
)
- Read Latest Emails:
await read_latest_emails(
email_identifier="your.email@gmail.com",
max_results=5,
download_attachments=False
)
- Download Attachments:
await download_email_attachments(
email_identifier="your.email@gmail.com",
msg_id="message_id",
download_all_in_thread=False
)
Security Considerations
- Store
client_secret.json securely and never commit it to version control - Keep token files secure and add them to
.gitignore - Use environment variables for sensitive information
- Regularly rotate OAuth credentials
- Monitor API usage and set appropriate quotas
Error Handling
The server includes comprehensive error handling and logging:
- Logs are written to
gmail_mcp.log - Both file and console logging are enabled
- Detailed error messages for debugging
Contributing
- Fork the repository
- Create a feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request
License
Apachelicense2.0
Support
For issues and feature requests, please use the GitHub issue tracker.