Google Workspace MCP server for AI agents

The Google Workspace MCP Server enables interaction with Gmail and Calendar APIs through the Model Context Protocol interface, allowing programmatic management of emails and calendar events with a comprehensive set of tools for both services.

Prerequisites

Node.js version 14 or higher
Google Cloud Console setup with the following:
- A Google Cloud project
- Gmail API and Google Calendar API enabled
- OAuth 2.0 credentials configured

Installation and Setup

Step 1: Set Up Google Cloud Project

Go to Google Cloud Console
Create a new project or select an existing one
Enable required APIs:
- Navigate to "APIs & Services" > "Library"
- Search for and enable "Gmail API"
- Search for and enable "Google Calendar API"
Create OAuth credentials:
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "OAuth client ID"
- Select "Web application"
- Add http://localhost:4100/code to "Authorized redirect URIs"
- Note your Client ID and Client Secret

Step 2: Install the Server

git clone https://github.com/epaproditus/google-workspace-mcp-server.git
cd google-workspace-mcp-server
npm install

Step 3: Configure OAuth Credentials

Create a credentials.json file in the root directory:

{
    "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"
    }
}

Step 4: Generate a Refresh Token

Run the provided script to authenticate and generate a refresh token:

node get-refresh-token.js

This will:

Open your browser for Google OAuth authentication
Request necessary permissions for Gmail and Calendar
Save credentials to token.json
Display your refresh token in the console

Step 5: Configure MCP Settings

Add server configuration to your MCP settings file based on your Claude environment:

VSCode Claude extension: Edit ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Claude desktop app: Edit ~/Library/Application Support/Claude/claude_desktop_config.json

Add this to the mcpServers object:

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/path/to/google-workspace-server/build/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Step 6: Build and Run

npm run build

Usage Examples

Gmail Operations

List Recent Emails

{
  "maxResults": 5,
  "query": "is:unread"
}

Search Emails with Advanced Filters

{
  "query": "from:[email protected] has:attachment",
  "maxResults": 10
}

Send an Email

{
  "to": "[email protected]",
  "subject": "Hello",
  "body": "Message content",
  "cc": "[email protected]",
  "bcc": "[email protected]"
}

Modify Email Labels

{
  "id": "message_id",
  "addLabels": ["UNREAD"],
  "removeLabels": ["INBOX"]
}

Calendar Operations

List Calendar Events

{
  "maxResults": 10,
  "timeMin": "2024-01-01T00:00:00Z",
  "timeMax": "2024-12-31T23:59:59Z"
}

Create a Calendar Event

{
  "summary": "Team Meeting",
  "location": "Conference Room",
  "description": "Weekly sync-up",
  "start": "2024-01-24T10:00:00Z",
  "end": "2024-01-24T11:00:00Z",
  "attendees": ["[email protected]"]
}

Update an Existing Event

{
  "eventId": "event_id",
  "summary": "Updated Meeting Title",
  "location": "Virtual",
  "start": "2024-01-24T11:00:00Z",
  "end": "2024-01-24T12:00:00Z"
}

Delete a Calendar Event

{
  "eventId": "event_id"
}

Troubleshooting

Authentication Issues

Ensure all required OAuth scopes are granted
Verify your client ID and secret are correct
Check if your refresh token is valid and not expired

API Errors

Check your Google Cloud Console for API quotas and limits
Ensure both Gmail and Calendar APIs are enabled for your project
Verify your request parameters match the required format

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "google-workspace" '{"command":"node","args":["/path/to/google-workspace-server/build/index.js"],"env":{"GOOGLE_CLIENT_ID":"your_client_id","GOOGLE_CLIENT_SECRET":"your_client_secret","GOOGLE_REFRESH_TOKEN":"your_refresh_token"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "google-workspace": {
            "command": "node",
            "args": [
                "/path/to/google-workspace-server/build/index.js"
            ],
            "env": {
                "GOOGLE_CLIENT_ID": "your_client_id",
                "GOOGLE_CLIENT_SECRET": "your_client_secret",
                "GOOGLE_REFRESH_TOKEN": "your_refresh_token"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "google-workspace": {
            "command": "node",
            "args": [
                "/path/to/google-workspace-server/build/index.js"
            ],
            "env": {
                "GOOGLE_CLIENT_ID": "your_client_id",
                "GOOGLE_CLIENT_SECRET": "your_client_secret",
                "GOOGLE_REFRESH_TOKEN": "your_refresh_token"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect