Google Workspace MCP Server

An MCP (Model Context Protocol) server that enables AI assistants to interact with your Google Workspace, specifically Gmail and Google Docs.

Overview

This server provides tools that allow AI agents to safely construct drafts, send emails, and append formatted content to Google Docs on your behalf.

Prerequisites

• Node.js 20+
• A Google Cloud project with the following APIs enabled:
  • Gmail API
  • Google Docs API
• OAuth 2.0 Credentials (Desktop application)

Google Cloud Setup

1. Create a Google Cloud Project: Go to the Google Cloud Console and create a new project.
2. Enable APIs: Navigate to "APIs & Services" > "Library" and enable:
   • Gmail API
   • Google Docs API
3. Configure OAuth Consent Screen:
   • Choose "External" (or "Internal" if you have a Google Workspace org).
   • Add the following scopes:
     • https://www.googleapis.com/auth/gmail.compose
     • https://www.googleapis.com/auth/documents
4. Create Credentials:
   • Go to "Credentials" > "Create Credentials" > "OAuth client ID"
   • Application type: "Desktop app"
   • Download the JSON file and save it as credentials.json in the root of this project.

Installation

npm install

Configuration

Create a .env file in the root directory:

# OAuth Credentials (Alternative to credentials.json file)
# GOOGLE_CLIENT_ID=your-client-id
# GOOGLE_CLIENT_SECRET=your-client-secret
# GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback

# MCP Configuration
MCP_SERVER_NAME=google-workspace-mcp
MCP_SERVER_VERSION=1.0.0
MCP_TRANSPORT=stdio

# Logging
LOG_LEVEL=info

# Storage
TOKEN_STORE_LOCATION=tokens.json

Authentication

Before running the server, you need to authorize it to act on your behalf. Run the interactive authentication script:

npm run auth

Follow the prompts to click the link, authorize the app, and paste the authorization code back into the terminal. This will create a tokens.json file.

Troubleshooting Authentication

"Access blocked: App has not completed the Google verification process" If you see this Error 403 access_denied, it means your Google Cloud project's OAuth Consent Screen is in "Testing" mode, and the email you are trying to log in with is not added as a test user. Fix: Go to your Google Cloud Console - OAuth Consent Screen. Scroll down to "Test users", click "+ Add Users", and add the email address you are trying to authenticate with.

"Google hasn't verified this app" Warning This is normal for personal projects in "Testing" mode. Fix: Simply click "Advanced" and then click "Go to [Your App Name] (unsafe)" to proceed with authentication.

Running the Server

Start the server using stdio transport (standard for most MCP clients like Cursor/Antigravity):

npm run build
npm run start

For development:

npm run dev

Available Tools

gmail_create_draft

Creates a draft email in your Gmail account.

• Parameters: to (array of strings), cc (optional), bcc (optional), subject (string), body (string - HTML support).

gmail_send_email

Sends an email directly from your Gmail account. ⚠️ Warning: Use with caution, this sends real emails immediately.

• Parameters: to (array of strings), cc (optional), bcc (optional), subject (string), body (string - HTML support).

google_docs_append_content

Appends formatted content (headings, paragraphs, lists) to the end of an existing Google Doc.

• Parameters:
  • documentId: The ID from the Google Doc URL (e.g. docs.google.com/document/d/{documentId}/edit)
  • content: An array of block objects (heading, paragraph, bulletList, numberedList).

Development

• Build: npm run build
• Typecheck: npm run typecheck
• Lint: npm run lint

Docker

Build the image:

docker build -t google-workspace-mcp .

Run the container (mounting the credentials and tokens files):

docker run -i \
  -v $(pwd)/credentials.json:/app/credentials.json \
  -v $(pwd)/tokens.json:/app/tokens.json \
  -e GOOGLE_APPLICATION_CREDENTIALS=/app/credentials.json \
  google-workspace-mcp

Security Considerations

• Never commit credentials.json, tokens.json, or .env to version control.
• The built-in logger redacts properties named token, secret, password, body, and content.
• Tokens are stored locally on your machine in the file specified by TOKEN_STORE_LOCATION.