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:
pip install .
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.jsonin 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:
python gmail_server.py
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.jsonand 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
python gmail_server.py
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.
Available Tools
- 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.jsonsecurely 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.
Metadata
Release files for iflow-mcp_quantum-369-gmail-server 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_quantum_369_gmail_server-0.1.0.tar.gz | 13.7 kB | Without provenance | Details for iflow_mcp_quantum_369_gmail_server-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_quantum_369_gmail_server-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_quantum_369_gmail_server-0.1.0-py3-none-any.whl |
Total release size: 30.9 kB
Release files / iflow_mcp_quantum_369_gmail_server-0.1.0.tar.gz
| Download URL | iflow_mcp_quantum_369_gmail_server-0.1.0.tar.gz |
|---|---|
| Size | 13.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b2124cb9a32e51f37b05f1b35e68e378fcab2ced39b8f8352fe94c5f9938a891
|
|
BLAKE2b-256 checksum How to use checksums |
c5896e28e8b1ebbbfaf0502eca8e46a43b686c84ddb652f70d024a0451162ef3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_quantum_369_gmail_server-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_quantum_369_gmail_server-0.1.0-py3-none-any.whl |
|---|---|
| Size | 17.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5e574507d90466a2bdefb96e9b69b71c70a96b17bbc61e8dbb395808d49dea3a
|
|
BLAKE2b-256 checksum How to use checksums |
0a118fc9cfa5f50fc0cabb446ab272fcae51083006ddf701cb4f879a5b8ed8cf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_quantum-369-gmail-server 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.