Google Workspace MCP server

The Google Workspace MCP server provides seamless integration between your AI assistants and Google Workspace services, giving you powerful control over Gmail, Calendar, Drive, and Contacts. After a simple, secure authentication process, you can manage your Google services directly through your AI assistant with advanced capabilities that go beyond standard interfaces.

Installation Requirements

Prerequisites

1. Google Cloud Project Setup:

   • Create a project in Google Cloud Console
   • Enable Gmail API, Calendar API, and Drive API
   • Configure OAuth consent screen as "External"
   • Add yourself as a test user

2. OAuth Credentials:

   • Create OAuth 2.0 credentials
   • Choose "Web application" type
   • Set redirect URI to: http://localhost:8080
   • Save your Client ID and Client Secret

3. Local Setup:

   • Install Docker
   • Create config directory:

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

   • If the directory already exists, ensure your user owns it

Configuration

Adding the Server to MCP Client

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-p", "8080:8080",
        "-v", "~/.mcp/google-workspace-mcp:/app/config",
        "-v", "~/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-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

For Cline (~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-p", "8080:8080",
        "-v", "~/.mcp/google-workspace-mcp:/app/config",
        "-v", "~/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-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Configuration Notes

• Port mapping -p 8080:8080 is required for OAuth callback handling
• Replace placeholder credentials with your actual Google Cloud OAuth credentials
• The LOG_MODE=strict setting is recommended but not required

Logging Modes

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

Authentication Process

1. Restart your MCP client after configuration
2. Ask your AI assistant to "add my Google account"
3. Follow the OAuth flow:
   • Click the provided authorization URL
   • Sign in to Google and grant permissions
   • Copy the authorization code from the success page
   • Provide the code back to complete authentication

Using the MCP Server

Account Management

• List configured accounts: Ask the assistant to "list my Google accounts"
• Add a new account: Ask to "add my Google account"
• Remove an account: Ask to "remove my Google account"

Gmail Capabilities

• Search emails: "Find emails from John with attachments sent last week"
• Send emails: "Send an email to [email protected] with the subject 'Meeting Notes'"
• Manage labels: "Create a new label called 'Important Projects'"
• Set up filters: "Create a filter to label all emails from my team as 'Team Updates'"

Calendar Management

• List events: "Show my calendar events for next week"
• Create events: "Schedule a meeting with Sarah on Friday at 2pm for 1 hour"
• Update events: "Reschedule tomorrow's marketing meeting to Thursday"
• Delete events: "Cancel my 3pm appointment today"

Drive Operations

• Browse files: "List my recent Google Drive documents"
• Search content: "Find presentations containing 'quarterly results'"
• Upload files: "Upload the report.pdf file to my Google Drive"
• Download files: "Download the budget spreadsheet from my Drive"
• Manage sharing: "Share my project proposal with [email protected]"

Contacts Access

• Retrieve contacts: "Find contact information for John Smith"

Troubleshooting

Common Issues

Authentication Errors:

• Verify OAuth credentials are correctly configured
• Ensure APIs (Gmail, Calendar, Drive) are enabled in Google Cloud
• Check that you're added as a test user in OAuth consent screen
• Confirm redirect URI is set to http://localhost:8080

Connection Issues:

• Verify port 8080 is available and not blocked by firewall
• Ensure Docker has permission to bind to port 8080
• Check that config directory exists and has proper permissions

Docker Issues (macOS):

• Shut down Docker fully with pkill -SIGHUP -f /Applications/Docker.app 'docker serve'
• Restart Docker Desktop
• Restart your MCP client

Docker Issues (Windows):

• End the "Docker Desktop" process in Task Manager
• Restart Docker Desktop from the Start menu
• Restart your MCP client

Token Issues:

• Remove and re-authenticate accounts if tokens become invalid
• Verify API scopes are properly configured in Google Cloud

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-mcp" '{"command":"docker","args":["run","--rm","-i","-p","8080:8080","-v","~/.mcp/google-workspace-mcp:/app/config","-v","~/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-client-id.apps.googleusercontent.com","GOOGLE_CLIENT_SECRET":"your-client-secret"}}'

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-mcp": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "-p",
                "8080:8080",
                "-v",
                "~/.mcp/google-workspace-mcp:/app/config",
                "-v",
                "~/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-client-id.apps.googleusercontent.com",
                "GOOGLE_CLIENT_SECRET": "your-client-secret"
            }
        }
    }
}

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-mcp": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "-p",
                "8080:8080",
                "-v",
                "~/.mcp/google-workspace-mcp:/app/config",
                "-v",
                "~/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-client-id.apps.googleusercontent.com",
                "GOOGLE_CLIENT_SECRET": "your-client-secret"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect