Epaproditus Google Workspace MCP Server

🚀 Google Workspace MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with Gmail and Calendar APIs. This server allows you to programmatically manage emails and calendar events through the MCP interface.

🚀 Quick Start

The Google Workspace MCP Server is a powerful tool that enables seamless interaction with Gmail and Calendar APIs. It simplifies the management of emails and calendar events through a user - friendly MCP interface.

✨ Features

Gmail Tools

• list_emails: List recent emails in the inbox with optional filtering.
• search_emails: Advanced email search using Gmail query syntax.
• send_email: Send new emails, supporting CC and BCC.
• modify_email: Modify email labels (archive, move to spam, mark as read/unread).

Calendar Tools

• list_events: List calendar events within a future range with date filtering.
• create_event: Create new calendar events, supporting attendees.
• update_event: Update existing calendar events.
• delete_event: Delete calendar events.

📦 Installation

Prerequisites

1. Node.js: Ensure Node.js is installed (recommended version 14 or higher).
2. Google Cloud Console Setup:
   • Create a project and enable the Google Workspace API and Calendar API.
   • Configure OAuth 2.0 credentials and grant the following scopes: https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/calendar

Setup Instructions

1. Clone the repository:

   git clone https://github.com/your-repository.git
   cd your-repository
   

2. Install dependencies:

   npm install
   

3. Create a credentials file:
   • Create a credentials.json file in the Google Cloud Console. Example content:

     {
       "type": "service_account",
       "project_id": "your-project-id",
       "private_key_id": "your-private-key-id",
       "client_email": "your-service-account@your-project-id.iam.gserviceaccount.com",
       "private_key": "your-private-key",
       "client_id": "your-client-id",
       "auth_uri": "https://accounts.google.com/o/oauth2/auth",
       "token_uri": "https://oauth2.googleapis.com/token",
       "AuthProviderLink": "https://www.googleapis.com/auth/",
       "Authority": "https://accounts.google.com/o/oauth2/auth"
     }
     

4. Get a refresh token:

   npm run get-refresh-token
   

Configure MCP Settings

1. Configure MCP settings for different IDEs according to the following paths:
   • VS Code: ~/.config/google/workspace-mcp/setting.json
   • IntelliJ IDEA: File > Settings > Google Workspace MCP Config
   • PyCharm: File > Settings > Google Workspace MCP Config
2. Example configuration content:

   {
     "gmail": {
       "apiKey": "your-gmail-api-key",
       "refreshToken": "your-refresh-token"
     },
     "calendar": {
       "apiKey": "your-calendar-api-key",
       "refreshToken": "your-refresh-token"
     }
   }
   

Build and Run

npm run build
npm start

💻 Usage Examples

Gmail Examples

Basic Usage

{
  "command": "list_emails",
  "maxResults": 10,
  "q": "subject:meeting"
}

Advanced Usage

{
  "command": "send_email",
  "to": "recipient@example.com",
  "subject": "Test Email",
  "body": "This is the content of the test email."
}

Calendar Examples

Basic Usage

{
  "command": "create_event",
  "summary": "Team Meeting",
  "location": "Meeting Room",
  "description": "Weekly sync",
  "start": "2024-01-24T10:00:00Z",
  "end": "2024-01-24T11:00:00Z",
  "attendees": ["colleague@example.com"]
}

🔧 Troubleshooting

Authentication Issues

• Ensure all required OAuth scopes are authorized.
• Verify that the client ID and secret are correct.
• Check the validity of the refresh token.

API Errors

• Check API quotas and limits in the Google Cloud Console.
• Ensure APIs are enabled for your project.
• Verify that request parameters are in the required format.

📄 License

This project is licensed under the MIT License.