mcp-google-services

CloudBoostUP/mcp-google-services

3.2

If you are the rightful owner of mcp-google-services and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Google Services MCP Server is a comprehensive solution for integrating and automating interactions with various Google services through the Model Context Protocol.

Tools
5
Resources
0
Prompts
0

Google Services MCP Server

A Model Context Protocol (MCP) server for automated Gmail backup and Google services management. This server provides scalable, automated email backup without manual Google Takeout processes.

🎯 Purpose

This MCP server enables:

  • Automated Gmail Backup: Scheduled email backup using Gmail API
  • MBOX Export: Export emails in standard MBOX format for portability
  • Multiple Export Formats: JSON, CSV, EML, and MBOX support
  • Incremental Backup: Only backup new/changed emails since last backup
  • Google Services Integration: Extensible framework for future Google services

🚀 Features

Currently Implemented (Gmail)

  • ✅ Gmail API Integration: Direct access to Gmail messages and metadata
  • ✅ Automated Backup: Full and incremental backup support
  • ✅ MBOX Format Export: RFC 4155 compliant MBOX file generation
  • ✅ Multiple Export Formats: MBOX, JSON, CSV, EML
  • ✅ Label Management: List and filter by Gmail labels
  • ✅ Message Search: Query messages with Gmail search syntax
  • ✅ Send Emails: Send email messages via Gmail API
  • ✅ Rate Limiting: Intelligent API quota management
  • ✅ Authentication: OAuth 2.0 with Application Default Credentials support

Planned Features

  • 📅 Scheduling System: Automated backup scheduling (cron-based)
  • 🔄 Additional Google Services: Drive, Calendar, Sheets, Docs, Photos, Contacts
  • 📊 Progress Tracking: Real-time backup progress monitoring
  • 🔒 Compression: Optional backup compression for storage efficiency
  • 🔐 Encryption: Optional encryption for sensitive data

📋 Prerequisites

  • Python 3.8 or higher
  • Google Cloud Project with Gmail API enabled
  • OAuth 2.0 credentials (for Gmail API access)
  • Required Python packages (see requirements.txt)

🛠️ Quick Start

1. Clone the Repository

git clone https://github.com/CloudBoostUP/mcp-google-services.git
cd mcp-google-services

2. Install Dependencies

pip install -r requirements.txt

3. Set Up Google API Credentials

Gmail API requires OAuth 2.0 credentials file. gcloud auth application-default login does not support Gmail scopes and cannot be used for Gmail API access.

OAuth 2.0 Credentials File (Required)
  1. Go to Google Cloud Console
  2. Create a new project or select existing one
  3. Enable Gmail API:
    • Navigate to "APIs & Services" > "Library"
    • Search for "Gmail API"
    • Click "Enable"
  4. Create OAuth 2.0 Credentials:
    • Navigate to "APIs & Services" > "Credentials"
    • Click "Create Credentials" > "OAuth client ID"
    • Choose "Desktop app" as application type
    • Download the JSON file
  5. Place credentials in config/credentials.json: 
    mkdir -p config
cp ~/Downloads/your-credentials.json config/credentials.json

4. Configure MCP Server in Cursor

Add to your Cursor MCP configuration (~/.cursor/mcp.json or .vscode/mcp.json):

Option A: Quick Start (Recommended - No Local Clone Required)

Use pipx to run directly from GitHub (similar to npx for npm packages):

{
  "mcpServers": {
    "google-services": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/CloudBoostUP/mcp-google-services.git",
        "python",
        "-m",
        "mcp_google_services.server"
      ],
      "env": {
        "GOOGLE_APIS_CREDENTIALS_PATH": "/path/to/your/config/credentials.json"
      }
    }
  }
}

Prerequisites for Option A:

  • Install pipx if not already installed: 
    python3 -m pip install --user pipx
  • Place your OAuth credentials file in a location accessible to the MCP server
  • Set the GOOGLE_APIS_CREDENTIALS_PATH environment variable to point to your credentials file

Note: When using pipx run, the server runs from a temporary virtual environment. Use the env section in the MCP configuration to specify the absolute path to your credentials file.

Option B: Local Development Setup

If you want to clone and develop locally:

{
  "mcpServers": {
    "google-services": {
      "command": "python",
      "args": [
        "-m",
        "mcp_google_services.server"
      ],
      "cwd": "/path/to/mcp-google-services"
    }
  }
}

Prerequisites for Option B:

  • Clone the repository: 
    git clone https://github.com/CloudBoostUP/mcp-google-services.git
cd mcp-google-services
pip install -r requirements.txt

Restart Cursor to load the MCP server.

🚀 Usage

Using MCP Tools in Cursor

Once the server is configured, you can use natural language commands:

List Gmail Labels
"List my Gmail labels"
"Show me all Gmail labels"
List Gmail Messages
"List my Gmail messages"
"Show me recent emails from last week"
"List messages from sender@example.com"
"Find emails with attachments"
Backup Gmail Messages
"Backup my Gmail messages"
"Create a full backup of my Gmail"
"Do an incremental backup of my emails"
"Backup messages from the last month"
Export Gmail Messages
"Export my Gmail to JSON"
"Export my emails to CSV format"
"Export recent messages to MBOX"
Send Email Messages
"Send an email to recipient@example.com"
"Send email with subject 'Hello' and body 'Test message'"
"Send email with CC and BCC recipients"

MCP Tool Reference

gmail_list_labels

List all Gmail labels for a user.

Parameters:

  • user_id (string, optional): Gmail user ID (default: "me")

Example:

{
  "tool": "gmail_list_labels",
  "arguments": {
    "user_id": "me"
  }
}
gmail_list_messages

List Gmail messages with optional filtering.

Parameters:

  • user_id (string, optional): Gmail user ID (default: "me")
  • query (string, optional): Gmail search query (e.g., "from:example@gmail.com", "has:attachment")
  • max_results (integer, optional): Maximum number of messages (default: 10)

Example:

{
  "tool": "gmail_list_messages",
  "arguments": {
    "user_id": "me",
    "query": "from:example@gmail.com newer_than:7d",
    "max_results": 20
  }
}
gmail_backup

Backup Gmail messages to MBOX format.

Parameters:

  • user_id (string, optional): Gmail user ID (default: "me")
  • backup_type (string, optional): "incremental" or "full" (default: "incremental")
  • max_results (integer, optional): Maximum number of messages (default: 1000)
  • query (string, optional): Gmail search query to filter messages

Example:

{
  "tool": "gmail_backup",
  "arguments": {
    "user_id": "me",
    "backup_type": "incremental",
    "max_results": 1000
  }
}
gmail_export

Export Gmail messages to various formats.

Parameters:

  • user_id (string, optional): Gmail user ID (default: "me")
  • format (string, optional): Export format - "mbox", "json", "csv", "eml" (default: "mbox")
  • output_path (string, optional): Output file path (auto-generated if not provided)
  • max_results (integer, optional): Maximum number of messages (default: 100)
  • query (string, optional): Gmail search query to filter messages

Example:

{
  "tool": "gmail_export",
  "arguments": {
    "user_id": "me",
    "format": "json",
    "max_results": 100
  }
}
gmail_send_message

Send an email message via Gmail API.

Parameters:

  • user_id (string, optional): Gmail user ID (default: "me")
  • to (string, required): Recipient email address
  • subject (string, required): Email subject
  • body (string, optional): Plain text email body (required if body_html not provided)
  • body_html (string, optional): HTML email body (optional, if provided will be used instead of body)
  • cc (array, optional): List of CC email addresses
  • bcc (array, optional): List of BCC email addresses
  • reply_to (string, optional): Reply-To email address

Example:

{
  "tool": "gmail_send_message",
  "arguments": {
    "to": "recipient@example.com",
    "subject": "Hello",
    "body": "This is a test email",
    "cc": ["cc@example.com"]
  }
}

📁 Project Structure

mcp-google-services/
├── src/
│   └── mcp_google_services/
│       ├── server.py              # MCP server implementation
│       ├── core/
│       │   ├── auth.py            # OAuth 2.0 authentication
│       │   ├── client.py          # Google API client base
│       │   ├── rate_limiter.py    # API quota management
│       │   └── scheduler.py      # Backup scheduling (planned)
│       ├── services/
│       │   └── gmail/
│       │       ├── api.py         # Gmail API client
│       │       ├── backup.py     # Backup operations
│       │       ├── export.py     # Export operations
│       │       ├── mbox.py        # MBOX format generation
│       │       └── parser.py     # Email parsing
│       └── utils/
│           └── config.py          # Configuration management
├── config/
│   ├── config.example.json        # Example configuration
│   └── credentials.json           # Google API credentials (not in git)
├── backups/
│   └── gmail/                     # Backup files (MBOX format)
├── exports/
│   └── gmail/                     # Export files (various formats)
├── docs/
│   ├── AUTHENTICATION.md          # Authentication setup guide
│   ├── architecture/              # Architecture documentation
│   └── specifications/             # Technical specifications
├── tests/                         # Test suite
├── requirements.txt               # Python dependencies
├── pyproject.toml                 # Project configuration
├── README.md                      # This file
└── CONTRIBUTING.md                # Contribution guidelines

🔧 Configuration

Configuration File

Create config/config.json from the example:

cp config/config.example.json config/config.json

Example configuration:

{
  "google_apis": {
    "credentials_path": "config/credentials.json"
  },
  "services": {
    "gmail": {
      "backup_folder": "backups/gmail",
      "max_messages_per_batch": 100
    }
  }
}

Environment Variables

export GOOGLE_APPLICATION_CREDENTIALS="path/to/credentials.json"
export MCP_GMAIL__BACKUP_FOLDER="backups/gmail"

📚 Documentation

  • - Detailed authentication setup
  • - Gmail API integration details
  • - How MBOX files are created
  • - Incremental vs full backup explained
  • - Common issues and solutions
  • - System architecture and design
  • - Detailed technical specs

🧪 Testing

# Run all tests
pytest

# Run specific test suite
pytest tests/test_services/test_gmail_integration.py

# Run with coverage
pytest --cov=mcp_google_services

🚨 Troubleshooting

Authentication Issues

Error: "No authentication credentials found"

  • Solution: Set up OAuth credentials file (required for Gmail API)

Error: "Gmail API scopes are required but not present"

  • Solution: Download OAuth 2.0 credentials from Google Cloud Console and place in config/credentials.json

Error: "Permission denied"

  • Solution: Ensure Gmail API is enabled in your Google Cloud project

See for more details.

🤝 Contributing

We welcome contributions! Please see for details.

Development Setup

# Install development dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

# Run linting
flake8 src/
black src/

📄 License

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

🆘 Support

🙏 Acknowledgments

  • Google API teams for excellent API documentation
  • Model Context Protocol community for MCP framework
  • CloudBoostUP team for project development

Made with ❤️ by CloudBoostUP

PRs Welcome License: MIT Python 3.8+