Google Connections MCP

A Model Context Protocol (MCP) server that provides AI assistants with access to Google Workspace APIs. Deploy once on Railway (or any hosting platform), connect from Claude or any MCP-compatible client.

Features

• Google Sheets - Full spreadsheet control with flexible row/column addressing (by header name or column letter), cell-level operations, and worksheet management

• Google Calendar - List, create, update, and delete events across all your calendars

• Gmail - Read, send, search, label, archive, and manage messages

• Google Tasks - Full task and task list management

• Google Drive - Search, list folders, create/move/rename/delete/share/copy files, download content

• Google Docs - Create documents, read/edit content, formatting (bold, italic, fonts, headings, bullets, margins)

• Time - Get current date/time in any IANA timezone

How It Works

1. You deploy this server to Railway (or similar)

2. You set up OAuth credentials in Google Cloud Console

3. You authorize with your Google account once

4. Your AI assistant connects to the server and can access your Google services

Each user deploys their own instance with their own credentials - your data stays yours.

Quick Start

Prerequisites

• Python 3.10+

• A Google Cloud project with OAuth 2.0 credentials

• Railway account (free tier works) or another hosting platform

• Claude.ai account (or another MCP-compatible client)

1. Google Cloud Setup

1. Go to Google Cloud Console

2. Create a new project (e.g., "My MCP Server")

3. Enable these APIs (APIs & Services → Enable APIs):

   • Google Calendar API

   • Gmail API

   • Google Drive API

   • Google Sheets API

   • Google Tasks API

4. Configure OAuth consent screen (APIs & Services → OAuth consent screen):

   • User Type: External

   • App name: Whatever you want (e.g., "My Google Connections")

   • User support email: Your email

   • Developer contact: Your email

   • Scopes: Add the following:

     • https://www.googleapis.com/auth/calendar

     • https://www.googleapis.com/auth/gmail.modify

     • https://www.googleapis.com/auth/gmail.send

     • https://www.googleapis.com/auth/drive

     • https://www.googleapis.com/auth/spreadsheets

     • https://www.googleapis.com/auth/tasks

   • Test users: Add your email

   • Important: Click "Publish App" to move from Testing to Production (this prevents tokens from expiring every 7 days)

5. Create OAuth 2.0 credentials (APIs & Services → Credentials):

   • Click "Create Credentials" → "OAuth client ID"

   • Application type: Web application

   • Name: Whatever you want

   • Authorized redirect URIs: https://your-app-name.up.railway.app/oauth/callback (Use your actual Railway URL - you'll get this after deploying)

   • Click "Create" and download the JSON file

2. Deploy to Railway

1. Fork this repository to your GitHub account

2. Go to Railway and create a new project

3. Choose "Deploy from GitHub repo" and select your fork

4. Railway will auto-detect the Python app and start deploying

5. Go to Settings → Networking → Generate Domain (note this URL)

6. Go back to Google Cloud and update your OAuth redirect URI with the actual Railway URL

7. Add environment variables in Railway (Settings → Variables):

   GOOGLE_CREDENTIALS = (paste the entire contents of your downloaded OAuth JSON file)

8. Trigger a redeploy after adding the environment variable

3. Authorize Your Google Account

1. Visit https://your-railway-url/oauth/start in your browser

2. Sign in with Google and grant permissions

3. You'll see a success message

4. Check Railway logs - you'll see the token JSON printed there

5. Important: Format the token correctly (see below)

6. Add it as environment variable: GOOGLE_TOKEN_JSON

7. Redeploy one more time

Formatting the Token JSON

Railway logs wrap the token in extra metadata. You need to extract just the token data.

What Railway logs show:

{
  "message": "",
  "attributes": {
    "token": "ya29.a0ARrdaM...",
    "refresh_token": "1//0eXy...",
    "token_uri": "https://oauth2.googleapis.com/token",
    "client_id": "12345...apps.googleusercontent.com",
    "client_secret": "GOCSPX-...",
    "scopes": ["https://www.googleapis.com/auth/calendar", ...],
    "expiry": "2025-12-15T12:00:00Z"
  },
  "tags": { ... },
  "timestamp": "2025-12-15T..."
}

What you need to paste (extract from attributes):

{"token": "ya29.a0ARrdaM...", "refresh_token": "1//0eXy...", "token_uri": "https://oauth2.googleapis.com/token", "client_id": "12345...apps.googleusercontent.com", "client_secret": "GOCSPX-...", "scopes": ["https://www.googleapis.com/auth/calendar", ...], "expiry": "2025-12-15T12:00:00Z"}

Quick method: Copy the Railway log output, paste it to Claude or ChatGPT, and ask: "Extract just the token JSON from this Railway log output and format it on one line."

4. Connect to Claude

1. In Claude.ai, go to Settings → Connections

2. Add a new MCP connection:

   • URL: https://your-railway-url/sse

3. The connection should show as active

You're done! Claude can now access your Google services.

Available Tools

Google Sheets

All Sheets tools support a mode parameter: "header" (default) uses column header names, "letter" uses column letters (A, B, C...).

Query Operators: ==, !=, >, <, >=, <=, in, not in, contains, not contains, is_null, not_null

Date Handling: Date columns are automatically parsed and compared correctly. Use == with full date strings (e.g., 1/27/2026 or 2026-01-27) for exact matching. Avoid contains for dates as it does substring matching.

Row Identification: Tools that modify rows accept either {"row": 6} for direct row numbers, or {"unique_id_column": "ID", "unique_id_value": "abc123"} for lookup-based identification.

Google Calendar

Timezone: create_calendar_event and update_calendar_event accept an optional timezone parameter (IANA format, e.g., 'America/New_York', 'Europe/London', 'UTC'). If omitted, uses the calendar's default timezone.

Gmail

Google Tasks

Google Drive

Download supports:

• Text files → returns text content

• PDFs → extracts and returns text (requires PyMuPDF)

• Google Docs → exports as plain text

• Google Sheets → exports as CSV

• Google Slides → exports as plain text

• Images → returns base64-encoded data

File operations:

• delete_file moves to trash by default; use permanent=True to delete forever

• share_file supports roles: reader, commenter, writer

• copy_file cannot copy folders, only files

Google Docs

Index positions: Google Docs uses 1-based indexing. Use get_doc_structure to see each paragraph with its start/end indices for precise formatting.

Bullet presets: BULLET_DISC_CIRCLE_SQUARE (default), BULLET_CHECKBOX, NUMBERED_DECIMAL_ALPHA_ROMAN, NUMBERED_DECIMAL_NESTED, and more.

Utility

Local Development

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

# Install uv if you don't have it
pip install uv

# Install dependencies
uv sync

# Set environment variables
export GOOGLE_CREDENTIALS='{"web":{"client_id":"..."}}'
export GOOGLE_TOKEN_JSON='{"token":"...","refresh_token":"..."}'

# Run the server
python -m google_connections_mcp.server

The server runs on port 8000 by default (or $PORT if set).

Environment Variables

*Not required for initial deploy - you'll add this after authorizing.

Endpoints

Troubleshooting

"Token expired" or constant reauthorization

Make sure you've published your OAuth app to Production in Google Cloud Console. Testing mode tokens expire every 7 days.

Can't connect from Claude

• Check that your Railway deployment is running (/health endpoint should return {"status": "ok"})

• Verify the URL is correct (should end in /sse)

• Check Railway logs for errors

OAuth callback fails

• Make sure your redirect URI in Google Cloud Console exactly matches your Railway URL

• The URL should be https:// (not http://)

• Include the full path: https://your-app.up.railway.app/oauth/callback

PDF text extraction not working

PyMuPDF should be included in dependencies. Check that your deployment includes it. PDFs will fall back to base64 if text extraction fails.

Architecture

This server uses:

• FastMCP for MCP protocol handling

• gspread for Google Sheets

• google-api-python-client for other Google APIs

• PyMuPDF for PDF text extraction

• Starlette for HTTP/SSE transport

• uv for fast dependency management

Known Limitations

• Images from Drive: Returned as base64. AI assistants need to decode and save locally to view.

• Large files: Very large files may timeout. Consider using get_drive_file for metadata and accessing via webViewLink instead.

• Google Workspace files: Docs/Sheets/Slides are exported to text/CSV, not native format.

License

MIT

Contributing

Issues and pull requests welcome!

Author

Michael Z Rork