Google Workspace MCP server

The Google Workspace MCP Server provides a powerful interface to control your Google Workspace services including Gmail, Calendar, and Drive. This server connects securely to your Google account and maintains that connection so you can interact with your Google services through AI assistants.

Installation Prerequisites

Before using this MCP server, you need to set up your own Google Cloud Project:

1. Create a new project in Google Cloud Console
2. Enable the required APIs:
   • Gmail API
   • Google Calendar API
   • Google Drive API
3. Configure the OAuth consent screen:
   • Set up as "External"
   • Add yourself as a test user
   • Add required scopes for Gmail, Calendar, and Drive
4. Create OAuth 2.0 credentials:
   • Choose "Desktop application" type
   • Note your Client ID and Client Secret
   • Use "urn:ietf:wg:oauth:2.0:oob" as the redirect URI (for out-of-band authentication)

Setup with Cline

1. Create a configuration directory:

   mkdir -p ~/.mcp/google-workspace-mcp
   

2. Add the following configuration to your Cline MCP settings (e.g., ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

   {
     "mcpServers": {
       "google-workspace-mcp": {
         "command": "docker",
         "args": [
           "run",
           "--rm",
           "-i",
           "-v", "/home/youruser/.mcp/google-workspace-mcp:/app/config",
           "-v", "/home/youruser/Documents/workspace-mcp-files:/app/workspace",
           "-e", "GOOGLE_CLIENT_ID",
           "-e", "GOOGLE_CLIENT_SECRET",
           "-e", "LOG_MODE=strict",
           "ghcr.io/aaronsb/google-workspace-mcp:latest"
         ],
         "env": {
           "GOOGLE_CLIENT_ID": "YOUR_GOOGLE_CLIENT_ID",
           "GOOGLE_CLIENT_SECRET": "YOUR_GOOGLE_CLIENT_SECRET"
         },
         "autoApprove": [],
         "disabled": false
       }
     }
   }
   

3. Replace YOUR_GOOGLE_CLIENT_ID and YOUR_GOOGLE_CLIENT_SECRET with your actual credentials

4. Update the file paths to match your username and preferred locations

5. Restart Cline/Claude

6. Ask the AI to "add my Google account" to start the authentication process

Logging Modes

• normal (default): Uses appropriate console methods for each log level
• strict: Routes all non-JSON-RPC messages to stderr (recommended for Claude desktop)

Manual Usage

You can run the container directly using Docker:

docker run -i --rm \
  -v ~/.mcp/google-workspace-mcp:/app/config \
  -v ~/Documents/workspace-mcp-files:/app/workspace \
  -e GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID \
  -e GOOGLE_CLIENT_SECRET=YOUR_GOOGLE_CLIENT_SECRET \
  -e LOG_MODE=strict \
  ghcr.io/aaronsb/google-workspace-mcp:latest

File Management

The server organizes files in a structured way:

~/Documents/workspace-mcp-files/
├── [[email protected]]/
│   ├── downloads/        # Files downloaded from Drive
│   └── uploads/          # Files staged for upload
├── [[email protected]]/
│   ├── downloads/
│   └── uploads/
└── shared/
    └── temp/             # Temporary files (cleaned up automatically)

You can customize the workspace location by setting the WORKSPACE_BASE_PATH environment variable.

Available Features

Account Management

• List, authenticate, and remove Google accounts
• Manage multiple accounts with different categories (work, personal)

Gmail Operations

• Search emails with advanced filtering
• Send emails with attachments and formatting
• Manage drafts, labels, and filters
• Access Gmail settings

Calendar Operations

• List, view, create, and manage calendar events
• Respond to invitations
• Create recurring events with attendees
• Handle time zone specifications

Drive Operations

• List, search, upload, and download files
• Create and manage folders
• Update sharing permissions and access controls
• Manage file metadata

Contacts Operations

• Retrieve and manage Google contacts
• Access contact information and details

Troubleshooting

Common Setup Issues

1. Missing Configuration

   • Error: "GOOGLE_CLIENT_ID environment variable is required"
   • Solution: Ensure you've properly configured the OAuth credentials in your MCP settings

2. Authentication Errors

   • Error: "Invalid OAuth credentials"
   • Solution: Verify your Google Cloud project configuration, API enablement, and test user setup

3. Token Issues

   • Error: "Token refresh failed"
   • Solution: Remove the account using remove_workspace_account and re-authenticate

4. Directory Structure

   • Error: "Directory not found"
   • Solution: Make sure the config directory exists with proper permissions
   • Run: mkdir -p ~/.mcp/google-workspace-mcp && chown $USER ~/.mcp/google-workspace-mcp

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.