Google MCP Server

A Model Context Protocol (MCP) server that integrates with Google APIs (Calendar, Drive, Gmail, Sheets, Docs) to provide seamless access to Google services through MCP-compatible clients.

Features

• Multiple Account Support: Manage multiple Google accounts with automatic context-aware selection
• Multi-Service Support: Integrated support for Google Calendar, Drive, Gmail, Sheets, and Docs
• OAuth 2.0 Authentication: Secure authentication with automatic token refresh
• MCP Protocol Compliant: Fully compliant with the Model Context Protocol specification
• Cross-Platform: Works on Windows, macOS, and Linux
• Configurable: Flexible configuration through JSON files or environment variables

Quick Start

macOS Quick Setup (Recommended)

# Install via Homebrew
brew tap ngs/tap
brew install google-mcp-server

# Configure Claude Desktop (Apple Silicon)
echo '{
  "mcpServers": {
    "google": {
      "command": "/opt/homebrew/bin/google-mcp-server"
    }
  }
}' > ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Run to authenticate (first time only)
google-mcp-server

For detailed setup instructions, see below.

Prerequisites

1. Google Cloud Project with APIs enabled
2. OAuth 2.0 credentials from Google Cloud Console
3. Go 1.23 or later (only for building from source)

Installation

Using Homebrew (macOS/Linux)

brew tap ngs/tap
brew install google-mcp-server

From Source

git clone https://github.com/ngs/google-mcp-server.git
cd google-mcp-server
go build

Using Go Install

go install go.ngs.io/google-mcp-server@latest

Pre-built Binaries

Download pre-built binaries from the releases page for:

• macOS (Intel & Apple Silicon)
• Linux (x86_64 & ARM64)
• Windows (x86_64)

Setup

1. Create a Google Cloud Project

   • Go to Google Cloud Console
   • Create a new project or select an existing one
   • Enable the required APIs:
     • Google Calendar API
     • Google Drive API
     • Gmail API
     • Google Sheets API
     • Google Docs API
     • Google Slides API

2. Create OAuth 2.0 Credentials

   • In Google Cloud Console, go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Choose "Desktop app" as the application type
   • Download the credentials JSON file

3. Configure the Server

   Create a config.json file:

   {
     "oauth": {
       "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
       "client_secret": "YOUR_CLIENT_SECRET",
       "redirect_uri": "http://localhost:8080/callback"
     },
     "services": {
       "calendar": {"enabled": true},
       "drive": {"enabled": true},
       "gmail": {"enabled": true},
       "sheets": {"enabled": true},
       "docs": {"enabled": true},
       "slides": {"enabled": true}
     }
   }
   

   Or use environment variables:

   export GOOGLE_CLIENT_ID="YOUR_CLIENT_ID.apps.googleusercontent.com"
   export GOOGLE_CLIENT_SECRET="YOUR_CLIENT_SECRET"
   

4. Run the Server

   ./google-mcp-server
   

   On first run, it will open a browser for authentication. Grant the requested permissions to proceed.

Available Tools

Account Management

• accounts_list - List all authenticated Google accounts
• accounts_details - Get detailed information about accounts
• accounts_add - Add a new Google account
• accounts_remove - Remove an authenticated account
• accounts_refresh - Refresh authentication token for an account

Google Calendar

• calendar_list - List all accessible calendars
• calendar_events_list - List events with date range filtering (supports account parameter)
• calendar_events_list_all_accounts - List events from all authenticated accounts
• calendar_event_create - Create new events (supports account parameter)
• calendar_event_update - Update existing events
• calendar_event_delete - Delete events
• calendar_event_get - Get event details
• calendar_freebusy_query - Query free/busy information
• calendar_event_search - Search for events

Google Drive

• drive_files_list - List files and folders (supports account parameter)
• drive_files_list_all_accounts - List files from all authenticated accounts
• drive_files_search - Search for files (supports account parameter)
• drive_file_download - Download files (supports account parameter)
• drive_file_upload - Upload files (supports account parameter)
• drive_markdown_upload - Upload Markdown content as formatted Google Docs (RECOMMENDED for Markdown)
• drive_markdown_replace - Replace Google Doc content with formatted Markdown
• drive_file_get_metadata - Get file metadata (supports account parameter)
• drive_file_update_metadata - Update file metadata (supports account parameter)
• drive_folder_create - Create folders (supports account parameter)
• drive_file_move - Move files (supports account parameter)
• drive_file_copy - Copy files (supports account parameter)
• drive_file_delete - Delete files (supports account parameter)
• drive_file_trash - Move files to trash (supports account parameter)
• drive_file_restore - Restore files from trash (supports account parameter)
• drive_shared_link_create - Create shareable links (supports account parameter)
• drive_permissions_list - List file permissions (supports account parameter)
• drive_permissions_create - Grant permissions (supports account parameter)
• drive_permissions_delete - Remove permissions (supports account parameter)

Google Gmail

• gmail_messages_list - List email messages (supports account parameter)
• gmail_messages_list_all_accounts - List messages from all authenticated accounts
• gmail_message_get - Get email details (supports account parameter)

Google Sheets

• sheets_spreadsheet_get - Get spreadsheet metadata
• sheets_values_get - Get cell values
• sheets_values_update - Update cell values
• (Additional tools in full implementation)

Google Docs

• docs_document_get - Get document content
• docs_document_create - Create new documents
• docs_document_update - Update document content (append or replace)

Google Slides

• slides_presentation_create - Create new presentation (supports account parameter)
• slides_presentation_get - Get presentation metadata (supports account parameter)
• slides_presentations_list_all_accounts - List presentations from all authenticated accounts
• slides_slide_create - Create new slide (supports account parameter)
• slides_slide_delete - Delete slide (supports account parameter)
• slides_slide_duplicate - Duplicate slide (supports account parameter)
• slides_markdown_create - Create presentation from Markdown with auto-pagination (supports account parameter)
• slides_markdown_update - Update presentation with Markdown content (supports account parameter)
• slides_markdown_append - Append slides from Markdown (supports account parameter)
• slides_add_text - Add text box to slide (supports account parameter)
• slides_add_image - Add image to slide (supports account parameter)
• slides_add_table - Add table to slide (supports account parameter)
• slides_add_shape - Add shape to slide (supports account parameter)
• slides_set_layout - Set slide layout (supports account parameter)
• slides_export_pdf - Export presentation as PDF (supports account parameter)
• slides_share - Create shareable link (supports account parameter)

Usage Examples

Multi-Account Support

The server supports managing multiple Google accounts simultaneously with automatic context-aware selection:

1. List authenticated accounts:

   • Use accounts_list to see all authenticated accounts
   • Shows email, name, last used time, and authentication status

2. Add additional accounts:

   • Use accounts_add to get an authorization URL
   • Complete the OAuth flow in your browser
   • The new account will be automatically added

3. Automatic account selection:

   • When you reference a specific email or domain, the server automatically selects the correct account
   • Example: "Create an event in john@example.com's calendar" will use John's account
   • You can explicitly specify an account using the account parameter in any tool
   • For ambiguous requests, the server will ask which account to use

4. Cross-account operations:

   • Use *_list_all_accounts tools to search across all authenticated accounts
   • Results are organized by account for clarity
   • Supported for Calendar (calendar_events_list_all_accounts), Gmail (gmail_messages_list_all_accounts), and Drive (drive_files_list_all_accounts)

With Claude Desktop

macOS (Homebrew Installation)

If you installed via Homebrew, add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "google": {
      "command": "/opt/homebrew/bin/google-mcp-server"
    }
  }
}

For Intel Macs, use /usr/local/bin/google-mcp-server instead.

Other Installations

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "google": {
      "command": "/path/to/google-mcp-server"
    }
  }
}

With Claude Code

Claude Code users can set up the Google MCP Server using either the claude mcp add command or manual configuration:

Method 1: Using claude mcp add (Recommended)

1. Install the server (if not already installed):

   # Using Homebrew (recommended for macOS)
   brew tap ngs/tap
   brew install google-mcp-server
   
   # Or build from source
   git clone https://github.com/ngs/google-mcp-server.git
   cd google-mcp-server
   go build
   

2. Add the MCP server to Claude Code:

   # If installed via Homebrew (Apple Silicon)
   claude mcp add google /opt/homebrew/bin/google-mcp-server
   
   # If installed via Homebrew (Intel Mac)
   claude mcp add google /usr/local/bin/google-mcp-server
   
   # If built from source
   claude mcp add google /path/to/your/google-mcp-server/google-mcp-server
   

3. Configure OAuth credentials:

   • Follow the Google Cloud Project setup steps above
   • Create a config.json file with your OAuth credentials in the current directory or home directory
   • Or set environment variables in your shell profile:

     export GOOGLE_CLIENT_ID="YOUR_CLIENT_ID.apps.googleusercontent.com"
     export GOOGLE_CLIENT_SECRET="YOUR_CLIENT_SECRET"
     

4. Authenticate (first time only):

   # Run the server directly to complete OAuth flow
   google-mcp-server
   # This will open a browser for authentication
   # Grant the requested permissions
   # The token will be saved to ~/.google-mcp-accounts/<email>.json
   

5. Restart Claude Code to apply the changes:

   # The MCP server will be available after restarting Claude Code
   

Method 2: Manual Configuration

1. Install the server (same as Method 1, step 1)

2. Configure OAuth credentials (same as Method 1, step 3)

3. Authenticate (same as Method 1, step 4)

4. Manually configure Claude Code:

   Add the MCP server to your Claude Code configuration. Create or edit ~/.claude/config.json:

   {
     "mcpServers": {
       "google": {
         "command": "/opt/homebrew/bin/google-mcp-server"
       }
     }
   }
   

   Or if you built from source:

   {
     "mcpServers": {
       "google": {
         "command": "/path/to/your/google-mcp-server/google-mcp-server"
       }
     }
   }
   

Verify the Setup

In Claude Code, you can test the connection by asking:

• "List my Google calendars"
• "Show my recent Gmail messages"
• "List files in my Google Drive"

Troubleshooting Claude Code Setup

• Check MCP server list: Run claude mcp list to verify the server is registered
• Remove and re-add: If issues persist, use claude mcp remove google then add it again
• Ensure executable permissions: chmod +x /path/to/google-mcp-server
• Verify token file: Check that token files exist in ~/.google-mcp-accounts/ after authentication
• Test server directly: Run google-mcp-server --version to ensure it works
• Check Claude Code logs: Look for MCP server errors in Claude Code output
• For multi-account issues: Check ~/.google-mcp-accounts/ directory for token files

Markdown to Slides Feature

The Google Slides integration includes powerful Markdown-to-Slides conversion with automatic pagination:

## Main Title
### Subtitle
(This creates a title slide with TITLE layout)

---

# Title Slide
Subtitle text

---

## Section Title
- Bullet point 1
- Bullet point 2
  - Nested bullet

---

### Content Slide
Regular paragraph text

**Bold text** and *italic text*

1. Numbered list
2. Second item

---

## Image Slide

![Image Caption - This will appear below the image](https://example.com/image.png)

Images are rendered at 50% of slide size and centered

---

| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |

---

```code
// Code block
function example() {
  return true;
}

Features:
- **Auto-pagination**: Content automatically flows to new slides when exceeding page limits
- **Force page breaks**: Use `---` to explicitly create new slides
- **Configurable font size**: Default 14pt with automatic line height calculation
- **Smart layout**: Titles, bullets, tables, images, and code blocks are properly formatted
- **Image support**: 
  - Images rendered at 50% of slide size, centered
  - Alt text displayed as caption below the image
  - Automatic TITLE_ONLY layout for slides with images
- **Title slide detection**: Slides with only two headings automatically use the TITLE layout for better visual presentation
- **Layout optimization**: 
  - TITLE layout: Used for slides with only headings (perfect for title/section slides)
  - TITLE_AND_BODY layout: Used for regular content slides
  - TITLE_ONLY layout: Used for slides containing tables or images (provides more space)

### Programmatic Usage

```python
# Example: List upcoming calendar events
response = mcp_client.call_tool(
    "calendar_events_list",
    {
        "calendar_id": "primary",
        "time_min": "2024-01-01T00:00:00Z",
        "max_results": 10
    }
)

# Example: Create presentation from Markdown
response = mcp_client.call_tool(
    "slides_markdown_create",
    {
        "title": "My Presentation",
        "markdown": markdown_content,
        "account": "user@example.com"
    }
)

Configuration

Configuration File

The server looks for configuration in the following locations (in order):

1. config.json in the current directory
2. config.local.json in the current directory
3. ~/.google-mcp-server/config.json
4. /etc/google-mcp-server/config.json

Environment Variables

• GOOGLE_CLIENT_ID - OAuth client ID
• GOOGLE_CLIENT_SECRET - OAuth client secret
• GOOGLE_REDIRECT_URI - OAuth redirect URI
• GOOGLE_TOKEN_FILE - Token storage location
• DISABLE_<SERVICE> - Disable specific services (e.g., DISABLE_GMAIL=true)
• LOG_LEVEL - Logging level (debug, info, warn, error)

Google Workspace Support

This server supports both personal Google accounts (@gmail.com) and Google Workspace accounts. For Workspace accounts:

1. Admin Consent: Your Workspace administrator may need to approve the application
2. Domain Restrictions: Some organizations restrict third-party app access
3. API Limitations: Certain APIs may be disabled by your organization

Workspace Setup Guide

See WORKSPACE_SETUP.md for detailed instructions on configuring the server for Google Workspace environments.

Security Considerations

• Token Storage: OAuth tokens are stored locally in ~/.google-mcp-accounts/ directory with restricted permissions
• Multi-Account Tokens: Each account's token is stored in a separate file named by email address
• Scopes: Only request the minimum necessary scopes for your use case
• Credentials: Never commit OAuth credentials to version control
• Network: Use HTTPS for all API communications

Troubleshooting

Common Issues

1. Authentication Errors (403: access_denied)

   If you encounter a 403 access_denied error during OAuth authentication, see the detailed OAuth Setup Guide for step-by-step instructions.

   Quick checklist:

   • ✅ OAuth consent screen configured with all required fields
   • ✅ Your email added to "Test users" (if app is in testing mode)
   • ✅ All 5 Google APIs enabled (Calendar, Drive, Gmail, Sheets, Docs)
   • ✅ OAuth client type is "Desktop app"
   • ✅ All required scopes added in OAuth consent screen
   • ✅ Wait 5-10 minutes after changes for propagation

2. Configuration File Issues

   • Check for JSON syntax errors (extra quotes, missing commas)
   • Ensure client_id and client_secret are correctly formatted
   • Verify the config file path: ~/.google-mcp-server/config.json

3. Permission Denied

   • Confirm you've granted all requested permissions during OAuth flow
   • For Workspace accounts, check with your administrator

4. Rate Limiting

   • The server implements exponential backoff for rate limits
   • Consider reducing request frequency if issues persist

5. Token Expiration

   • Tokens are automatically refreshed
   • If refresh fails, re-authenticate by removing the account: accounts_remove then accounts_add
   • Or delete specific token file: rm ~/.google-mcp-accounts/<email>.json

Development

Building from Source

# Clone the repository
git clone https://github.com/ngs/google-mcp-server.git
cd google-mcp-server

# Install dependencies
go mod download

# Build
go build

# Run tests
go test ./...

# Run with race detector
go test -race ./...

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

API Rate Limits

Each Google API has its own rate limits:

• Calendar: 1,000,000 queries/day
• Drive: 1,000,000,000 queries/day
• Gmail: 250 quota units/user/second
• Sheets: 100 requests/100 seconds
• Docs: 60 requests/minute

The server implements automatic retry with exponential backoff when limits are reached.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Based on the Dropbox MCP implementation pattern
• Built on the Model Context Protocol specification
• Uses Google API Go Client Libraries

Support

For issues, questions, or contributions, please visit the GitHub repository.

Roadmap

• Full implementation of all Gmail tools
• Advanced Sheets operations (charts, pivots)
• Docs formatting and collaboration features
• Batch operations optimization
• Webhook support for real-time updates
• Multi-account management UI
• Docker container support