Gmail Plugin MCP Server

A powerful MCP server that enables Gmail integration, allowing you to manage emails directly through MCP clients. This plugin provides seamless access to Gmail's core functionality including reading, sending, and managing emails.

Reference: For a sample MCP server implementation using uvx, check out this example.

🎥 Demo

https://github.com/user-attachments/assets/df9e86cf-1f6b-4265-9c68-b3ed88103d1f

✨ Features

📧 Send and receive emails
📥 Read unread messages
🗑️ Trash emails
📱 Open emails in browser
📝 Mark emails as read
🔒 Secure OAuth2 authentication

🚀 Quick Start

Prerequisites

Python 3.12 or higher
Gmail API credentials
MCP client (like Claude Desktop)

Installation

Clone the repository:

git clone https://github.com/yourusername/gmail-plugin.git
cd gmail-plugin

Install dependencies (choose one method):

# Method 1: Install in editable mode
uv pip install -e .

# Method 2: Install using requirements.txt
uv pip install -r requirements.txt

# Method 3: Install using uv sync (recommended)
uv sync --dev --all-extras

Configure your Gmail API credentials:
- Go to Google Cloud Console
- Create a new project or select existing one
- Enable Gmail API
- Configure OAuth consent screen:
  - Select "External" user type (no publishing required)
  - Go to the Audiences tab : Add your email as a "Test user"
  - Add OAuth scope: https://www.googleapis.com/auth/gmail/modify
- Create OAuth 2.0 credentials:
  - Choose "Desktop App" as application type
  - Download the JSON credentials file
- Save the credentials file and note its absolute path (will be used for --creds-file-path)

Configuration

For Development/Unpublished Servers

Add this to your MCP client configuration:

"mcpServers": {
  "gmail-plugin": {
    "command": "uv",
    "args": [
      "--directory",
      "[absolute path to working directory]",
      "run",
      "server.py"
      "--creds-file-path",
      "[absolute-path-to-credentials-file]",
      "--token-path",
      "[absolute-path-to-access-tokens-file]"
    ]
  }
}

For Published Servers

"mcpServers": {
  "gmail-plugin": {
    "command": "uvx",
    "args": [
      "gmail-plugin"
    ]
  }
}

🛠️ Development

Building and Publishing

Sync dependencies:

uv sync

Build package:

uv build

Publish to PyPI:

uv publish

Debugging

Use the MCP Inspector for debugging:

npx @modelcontextprotocol/inspector uv --directory C:\Users\sanch\Desktop\gmail_plugin\gmail-plugin run gmail-plugin

📚 API Reference

Available Tools

Tool Name	Description	Required Arguments
`send-email`	Send an email	recipient_id, subject, message
`get-unread-emails`	Retrieve unread emails	None
`read-email`	Read email content	email_id
`trash-email`	Move email to trash	email_id
`mark-email-as-read`	Mark email as read	email_id
`open-email`	Open email in browser	email_id

Available Prompts

Prompt Name	Description	Arguments
`manage-email`	Act as email administrator	None
`draft-email`	Draft a new email	content, recipient, recipient_email
`edit-draft`	Edit existing email draft	changes, current_draft

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.