go.ngs.io/google-mcp-server

MCP server for Google Workspace APIs - Calendar, Drive, Gmail, Sheets, Docs, and Slides integration

go get go.ngs.io/google-mcp-server

Version:: v0.3.0
License:: MIT
Author:: "Atsushi
Repository:: https://github.com/ngs/google-mcp-server
Documentation:: https://pkg.go.dev/google-mcp-server
Last Updated:: 2025-09-10T20:08:21Z

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

Google Cloud Project with APIs enabled
OAuth 2.0 credentials from Google Cloud Console
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

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
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

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"

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:

List authenticated accounts:
- Use accounts_list to see all authenticated accounts
- Shows email, name, last used time, and authentication status
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
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
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)

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

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

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"
```

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

Restart Claude Code to apply the changes:

# The MCP server will be available after restarting Claude Code

Method 2: Manual Configuration

Install the server (same as Method 1, step 1)
Configure OAuth credentials (same as Method 1, step 3)
Authenticate (same as Method 1, step 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):

config.json in the current directory
config.local.json in the current directory
~/.google-mcp-server/config.json
/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:

Admin Consent: Your Workspace administrator may need to approve the application
Domain Restrictions: Some organizations restrict third-party app access
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

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
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
Permission Denied
- Confirm you’ve granted all requested permissions during OAuth flow
- For Workspace accounts, check with your administrator
Rate Limiting
- The server implements exponential backoff for rate limits
- Consider reducing request frequency if issues persist
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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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