mcp-gsuite MCP Server: Gmail and Calendar Integration

Overview: What is mcp-gsuite MCP Server?

The mcp-gsuite MCP server is designed to facilitate seamless integration between Google products and AI applications compliant with the Model Context Protocol (MCP). Specifically, it enables interaction with Gmail and Calendar services through structured API calls that are uniformly understood by compatible MCP clients. This server is particularly useful for developers working on AI applications like Claude Desktop, Continue, Cursor, and others who require access to complex email management and event planning functionalities.

🔧 Core Features & MCP Capabilities

The mcp-gsuite MCP server supports a wide range of capabilities, making it an indispensable tool for building sophisticated integrated solutions. These features include multiple Google accounts support, flexible Gmail queries, comprehensive calendar management tools, and more. Some key capabilities are:

1. Multiple Google Accounts: The ability to authenticate and manage data from multiple Google accounts within the same application.
2. Gmail Features:
   • Retrieve user information
   • Search emails using flexible criteria (unread, specific senders, date ranges, attachments)
   • Retrieve complete email content by ID
   • Create new draft emails with rich options like recipients, subject, body, and CC fields
   • Delete draft emails
   • Reply to existing emails (optionally save as draft or send immediately)
   • Retrieve multiple emails at once using their IDs
   • Save attachments from emails locally
3. Calendar Features:
   • Manage multiple calendars
   • Fetch calendar events within specified time ranges
   • Create new calendar events with details like title, start/end times, location, description, and attendees
   • Custom timezone support for event creation
   • Set notification preferences for events
   • Delete existing calendar events

⚙️ MCP Architecture & Protocol Implementation

The mcp-gsuite server follows the Model Context Protocol (MCP) to ensure compatibility with various AI applications. This protocol provides a standardized framework for data exchange, allowing efficient communication between different systems. The architecture of the mcp-gsuite server incorporates several components:

• OAuth2 Authentication: Utilizes OAuth2 for secure authentication against Google APIs.
• Event-driven Communication: Supports asynchronous message passing and event-driven patterns to handle interactions with Gmail and Calendar services efficiently.

The protocol flow is as follows:

graph TD
    A[AI Application] -->|MCP Client| B[MCP Protocol]
    B --> C[MCP Server]
    C --> D[Google APIs (Gmail/Calendar)]

This flow ensures that requests are handled in a secure and efficient manner, allowing seamless integration with AI applications.

🚀 Getting Started with Installation

Install via Smithery

To install the mcp-gsuite MCP server for use with Claude Desktop:

1. Install via CLI:

   npx -y @smithery/cli install mcp-gsuite --client claude
   

2. OAuth 2 Setup: Follow these steps to set up OAuth authentication:

   • Create OAuth2 Credentials:

     1. Go to the Google Cloud Console
     2. Create a new project or select an existing one
     3. Enable the Gmail API and Google Calendar API for your project
     4. Navigate to "Credentials" → "Create Credentials" → "OAuth client ID"
     5. Choose "Desktop app" as the application type
     6. Configure the OAuth consent screen with required information

   • Required OAuth2 Scopes:

     [
         "openid",
         "https://mail.google.com/",
         "https://www.googleapis.com/auth/calendar",
         "https://www.googleapis.com/auth/userinfo.email"
     ]
     

   • Create Authentication Configuration File (gauth.json):

     {
         "web": {
             "client_id": "$your_client_id",
             "client_secret": "$your_client_secret",
             "redirect_uris": ["http://localhost:4100/code"],
             "auth_uri": "https://accounts.google.com/o/oauth2/auth",
             "token_uri": "https://oauth2.googleapis.com/token"
         }
     }
     

   • Create Account Information File (accounts.json):

     {
         "accounts": [
             {
                 "email": "[email protected]",
                 "account_type": "personal",
                 "extra_info": "Contains Family Calendar"
             }
         ]
     }
     

   • Execute Tool for Authentication: When you first execute one of the tools, a browser will open asking for your credentials. Upon successful login, it stores the refresh token in a local file called .oauth.{email}.json.

Development/Unpublished Servers Configuration

For development or unpublished servers, update claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-gsuite": {
      "command": "uv",
      "args": [
        "--directory",
        "<dir_to>/mcp-gsuite",
        "run",
        "mcp-gsuite"
      ]
    }
  }
}

Customize with different accounts or credentials paths:

{
  "mcpServers": {
    "mcp-gsuite": {
      "command": "uv",
      "args": [
        "--directory",
        "<dir_to>/mcp-gsuite",
        "run",
        "mcp-gsuite",
        "--accounts-file",
        "/path/to/custom/.accounts.json",
        "--credentials-dir",
        "/path/to/custom/credentials"
      ]
    }
  }
}

Published Servers Configuration:

{
  "mcpServers": {
    "mcp-gsuite": {
      "command": "uvx",
      "args": [
        "mcp-gsuite",
        "--accounts-file",
        "/path/to/custom/.accounts.json",
        "--credentials-dir",
        "/path/to/custom/credentials"
      ]
    }
  }
}

💡 Key Use Cases in AI Workflows

Scenario 1: Email Integration

Imagine a scenario where an AI application is assisting with daily email management. The mcp-gsuite server allows for efficient querying and managing of emails based on specific criteria, such as unread messages from the Scrum Master or bulk operations like saving attachments to local storage.

Technical Implementation

Retrieve my latest unread messages
Search my emails from the Scrum Master
Take the email about ABC and save its attachment locally

Scenario 2: Calendar Management

In a project management context, an AI application can use mcp-gsuite to manage events across multiple calendars. This includes scheduling meetings with attendees in different time zones, setting reminders, and ensuring all team members are aware of upcoming events.

Technical Implementation

Fetch calendar events for the next week
Create new event for the sales meeting at 10 AM CST (Custom Timezone Support)
Set notification 24 hours before the sales meeting

🔌 Integration with MCP Clients

The mcp-gsuite server is fully compatible with several MCP clients, including:

• Claude Desktop: Full support
• Continue: Full support
• Cursor: Tools only (no prompt support)

This ensures a smooth and integrated experience across different AI application platforms.

📊 Performance & Compatibility Matrix

MCP Client Compatibility Matrix:

MCP Client	Resources	Tools	Prompts	Status
Claude Desktop	✅	✅	✅	Full Support
Continue	✅	✅	✅	Full Support
Cursor	❌	✅	❌	Tools Only

🛠️ Advanced Configuration & Security

For advanced configurations, refer to the mcp-gsuite server documentation. Key configuration elements include:

• Authentication Setup: Detailed steps for securing your OAuth credentials and setting up the authentication process.
• Environment Variables: Use environment variables to manage secrets like API keys securely.

❓ Frequently Asked Questions (FAQ)

1. How do I set up multiple Google accounts?
   • Create separate .accounts.json files for each account, updating the email field in each configuration.
2. Can this server handle large volumes of data?
   • Yes, it is designed to handle various data loads efficiently by utilizing asynchronous operations and event-driven patterns.
3. What are the security considerations for using OAuth2?
   • Securely store your client ID and secret. Avoid hardcoding credentials in your source code.
4. Are there performance issues with heavy API calls?
   • No, the mcp-gsuite server optimizes API calls to minimize latency and improve overall performance.
5. Can I use this server for other Google services besides Gmail and Calendar?
   • While primarily designed for Gmail and Calendar, similar setups can be created for other Google services by modifying the scope of your OAuth2 credentials.

👨‍💻 Development & Contribution Guidelines

Contributions are welcome! If you wish to contribute or report issues, please follow these steps:

1. Fork the Repository: Clone the mcp-gsuite server repository from GitHub.
2. Create Issues: Use the issue tracker to report bugs or suggest features.
3. Pull Requests (PRs): Propose code changes for review and integration.

For detailed development guidelines, see the CONTRIBUTING.md file in the repository.

🌐 MCP Ecosystem & Resources

Join the broader MCP community for discussions, support, and resources:

• MCP Website: Link to official website
• GitHub Repository: mcp-gsuite GitHub Page

These resources provide extensive documentation, forums, and additional tools to help you leverage Model Context Protocol effectively.

---

This comprehensive guide positions the mcp-gsuite MCP server as a robust solution for AI applications seeking seamless integration with Google products. By emphasizing technical details and real-world use cases, developers can harness its full potential in building sophisticated integrated systems.