robcerda/google-mcp-server

Google MCP Server

Connect Claude to your Google Workspace with intelligent contact resolution and secure OAuth2 authentication

Transform Claude into your Google productivity assistant. Send emails to "John Smith" instead of , share files by name, and create calendar events with automatic attendee resolution.

✨ Key Features

• 🧠 Smart Contact Resolution: send email to Spencer Varney about the meeting → automatically finds
• 🔒 Secure by Default: Uses restricted scopes compatible with Google Advanced Protection
• 📱 50+ Tools: Complete Gmail, Drive, Calendar integration with shared drive support
• ⚡ Safety First: All send/share operations require explicit confirmation

🚀 Quick Start

1. Install

git clone https://github.com/robcerda/google-mcp-server
cd google-mcp-server
uv sync

2. Configure Google

1. Create a Google Cloud project and enable APIs (Drive, Gmail, Calendar, People)
2. Create OAuth2 credentials (Desktop application type)
3. Copy your credentials to .env:

cp .env.example .env
# Edit .env with your GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET

3. Add to Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "google-services": {
      "command": "/path/to/google-mcp-server/.venv/bin/mcp",
      "args": ["run", "/path/to/google-mcp-server/server.py"]
    }
  }
}

💡 Examples

Smart Email (resolves contacts automatically):

Send an email to Spencer Varney about tomorrow's meeting

Safe File Sharing (shows preview, requires confirmation):

Share the Q4 report with the marketing team as editors

Calendar with Attendees (resolves multiple contacts):

Create a meeting tomorrow 2-3pm with Spencer, John, and Sarah

🔐 Security & Scopes

This server uses intentionally restrictive OAuth scopes for maximum security by default. These scopes are compatible with Google Advanced Protection Program and follow the principle of least privilege.

Default Scopes (Security-First)

• drive.file - Only files created by this app (not full Drive access)
• gmail.send + gmail.readonly + gmail.labels - Send, read, and manage labels
• contacts.readonly - Read contacts for smart name resolution
• calendar - Full calendar access (Google doesn't offer restricted calendar scopes)

Expanding Permissions

If you need broader access, add scopes to your .env file:

# Example: Full Drive access + Gmail modify
GOOGLE_ADDITIONAL_SCOPES=https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/gmail.modify

# Common broader scopes:
# https://www.googleapis.com/auth/drive - Full Google Drive access
# https://www.googleapis.com/auth/gmail.modify - Full Gmail modification
# https://www.googleapis.com/auth/spreadsheets - Google Sheets access
# https://www.googleapis.com/auth/contacts - Full contacts read/write

Security Note: The default restricted scopes protect your account even if credentials are compromised. Only expand permissions if you specifically need the additional functionality.

File: Scopes are defined in src/google_mcp_server/auth.py (DEFAULT_SCOPES)

📚 Documentation

• - Detailed Google Cloud Console configuration
• - Complete list of 50+ available tools
• - Common workflows and advanced usage
• - Solutions for common issues

🛡️ Safety Features

All potentially dangerous operations use a two-step confirmation process:

1. Prepare: prepare_send_email() → Shows preview, resolves contacts
2. Confirm: confirm_send_email() → Actually sends after your approval

No emails, file shares, or calendar invites are sent without explicit confirmation.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

📄 License

MIT License - see file for details.

Questions? Check the or open an issue.