google-connections

This Google Connections MCP server provides AI assistants with secure, per-user access to your Google Workspace data via a single MCP endpoint. It exposes tools that let you read and manipulate Google Sheets, manage Google Calendar events, access Gmail messages, work with Google Tasks, drive and organize Drive files, and create or edit Google Docs content, all while handling authentication through your Google Cloud project. Clients like Claude can connect to the server via its SSE endpoint and issue requests to the available tools to perform operations on your Google Workspace data. Each user runs their own instance and credentials, so your data remains private to your deployment.

To get started, deploy this MCP server to a hosting platform (Railway is commonly used), configure OAuth credentials in Google Cloud Console, and authorize once. After linking, the MCP server will be able to perform actions such as querying and updating spreadsheets, creating calendar events, sending or reading Gmail messages, managing Drive files, and editing Docs content on behalf of the authenticated user. Claude and other MCP-compatible clients can then connect to the server at the provided URL (typically https://your-app-url/sse) and begin issuing tool calls.

Key capabilities include the Google Sheets tools (querying data, reading rows, updating cells, and managing worksheets), Google Calendar tools (listing calendars and events, creating/updating/deleting events), Gmail tools (reading, sending, labeling, and organizing messages), Google Drive tools (searching, listing, creating, moving, sharing, and downloading content), Google Docs tools (creating and editing document content with formatting), and Google Tasks tools (full task list management). A Time tool is also available to fetch the current date/time in any IANA timezone.

Prerequisites:

• Python 3.10+
• A Google Cloud project with OAuth 2.0 credentials configured for web/mobile usage
• Access to a hosting provider (e.g., Railway) or a compatible deployment environment

1. Clone the repository git clone https://github.com/your-organization/google-connections-mcp.git cd google-connections-mcp

2. Create and configure Google Cloud OAuth credentials

   • In Google Cloud Console, create OAuth 2.0 Client IDs for a Web application
   • Set Authorized redirect URI to https://your-app-url/oauth/callback
   • Download the credentials JSON (rename to google_credentials.json or copy contents)

3. Set environment variables for deployment

   • GOOGLE_CREDENTIALS: Paste the entire contents of your downloaded OAuth JSON file
   • GOOGLE_TOKEN_JSON: After completing initial authorization, paste the token JSON you retrieved

4. Install dependencies

   • python -m ensurepip --upgrade
   • pip install -r requirements.txt

5. Run locally (for testing)

   • export GOOGLE_CREDENTIALS="<contents>"
   • export GOOGLE_TOKEN_JSON="<token-json>"
   • python -m google_connections

6. Deploy to Railway or another host

   • Push the repository to GitHub
   • Create a new project on Railway and connect the GitHub repo
   • In Railway, set environment variables: GOOGLE_CREDENTIALS = <contents of OAuth JSON> GOOGLE_TOKEN_JSON = <token-json>
   • Deploy and note the generated domain (e.g., https://your-app.up.railway.app)
   • Update OAuth redirect URI in Google Cloud Console to your Railway URL

7. Connect from an MCP client

   • Point your MCP client to https://your-app-url/sse
   • Complete the OAuth flow if prompted, and authorize the app

Tips and common issues:

• Each user should deploy their own instance with their own Google credentials; do not reuse credentials across users.
• Ensure the Google Cloud project has the required APIs enabled (Calendar, Gmail, Drive, Sheets, Tasks) and that OAuth scopes match the APIs you intend to use.
• After initial authorization, you may need to redeploy when rotating tokens or credentials.
• If you encounter token expiry issues, verify that the GOOGLE_TOKEN_JSON contains the correct expiry field and is refreshed after token rotation.
• When deploying behind a reverse proxy or custom domain, update the OAuth redirect URI to reflect the actual deployment URL.
• The available tools cover Sheets, Calendar, Gmail, Drive, Docs, and Tasks. Use the provided operator set (e.g., ==, !=, >, <, in, contains) to query and filter results efficiently.
• For debugging, check server logs for OAuth flow messages and make sure the environment variables are correctly loaded by the runtime.