Google Mcp Server

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

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

1. Configure the Server

Create a config.json file:

``json { "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: ``bash export GOOGLE_CLIENT_ID="YOUR_CLIENT_ID.apps.googleusercontent.com" export GOOGLE_CLIENT_SECRET="YOUR_CLIENT_SECRET" ``

1. Run the Server

``bash ./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

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

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

1. 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):

```bash # 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 ```

1. Add the MCP server to Claude Code:

```bash # 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 ```

1. 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:

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

1. Authenticate (first time only):

``bash # 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/.json ``

1. Restart Claude Code to apply the changes:

``bash # The MCP server will be available after restarting Claude Code ``

Method 2: Manual Configuration

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

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

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

1. Manually configure Claude Code:

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

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

Or if you built from source: ``json { "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

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_ - 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 [WORKSPACESETUP.md](WORKSPACESETUP.md) for detailed instructions on configuring the server for Google Workspace environments.

Security Considerations

• Token Storage: OAuth tokens are stored locally in `~/.google-

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ngs
• Source: ngs/google-mcp-server
• License: MIT
• Homepage: https://go.ngs.io/google-mcp-server

Install and usage instructions live in the source repository linked above.