Skip to main content
Glama
Sign In
Google Workspace MCP Server

Google Workspace MCP Server

by risvan1605
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Google Workspace MCP Server

A generic Model Context Protocol (MCP) Server that exposes Gmail and Google Docs as standardized tools, enabling any MCP-compatible AI agent (Claude, ChatGPT, Cursor, VS Code agents, etc.) to securely interact with Google Workspace.

Features

  • Gmail Tools — Draft, update, send, and retrieve emails

  • Google Docs Tools — Create, read, append to, and inspect documents

  • OAuth 2.0 — Secure authentication with automatic token refresh

  • MCP-Compliant — Works with any MCP client out of the box

  • Structured Responses — Consistent JSON response envelopes for all tools

  • Extensible — Modular architecture for adding Google Sheets, Drive, Calendar, etc.

Related MCP server: Gmail MCP Server

Prerequisites

  • Python 3.11+

  • A Google Cloud project with Gmail API and Google Docs API enabled

  • OAuth 2.0 credentials (credentials.json)

Google Cloud Setup

  1. Go to the Google Cloud Console

  2. Create a new project (or select an existing one)

  3. Navigate to APIs & Services → Library

  4. Enable Gmail API and Google Docs API

  5. Navigate to APIs & Services → Credentials

  6. Click Create Credentials → OAuth 2.0 Client ID

  7. Select Desktop app as the application type

  8. Download the credentials file and save it as credentials.json in the project root

  9. Navigate to OAuth consent screen and add your email as a test user

Installation

# Clone the repository
git clone <repository-url>
cd google-mcp-server

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

# Install the package
pip install -e .

# Install dev dependencies (optional)
pip install -e ".[dev]"

Configuration

Copy the environment template and configure:

cp .env.example .env

Edit .env as needed:

GOOGLE_CREDENTIALS_PATH=./credentials.json
GOOGLE_TOKEN_PATH=./token.json
LOG_LEVEL=INFO

First Run

On the first run, the server will open your browser for Google OAuth consent:

python -m google_mcp_server.server

  1. A browser window will open asking you to sign in to Google

  2. Grant the requested permissions (Gmail compose/read, Google Docs read/write)

  3. The token is saved to token.json for future use

  4. The server starts on stdio transport, ready for MCP client connections

Available Tools

Gmail

Tool

Description

draft_email

Create a new email draft with To, CC, BCC, Subject, and Body

update_email_draft

Update an existing draft (unchanged fields are preserved)

send_new_email

Send an email directly without creating a draft

send_existing_draft

Send a previously created draft

get_email_draft

Retrieve a draft by ID with headers and snippet

Google Docs

Tool

Description

create_google_doc

Create a new document with optional initial content

read_google_doc

Read the full text content of a document

append_to_google_doc

Append text to the end of a document

get_google_doc_metadata

Get document metadata (title, revision, URL)

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "google-workspace": {
      "command": "python",
      "args": ["-m", "google_mcp_server.server"],
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "/absolute/path/to/credentials.json",
        "GOOGLE_TOKEN_PATH": "/absolute/path/to/token.json"
      }
    }
  }
}

Cursor

Add to your MCP settings:

{
  "mcpServers": {
    "google-workspace": {
      "command": "python",
      "args": ["-m", "google_mcp_server.server"],
      "cwd": "/path/to/google-mcp-server"
    }
  }
}

VS Code (Copilot)

Add to your VS Code settings:

{
  "mcp": {
    "servers": {
      "google-workspace": {
        "command": "python",
        "args": ["-m", "google_mcp_server.server"],
        "cwd": "/path/to/google-mcp-server"
      }
    }
  }
}

Vercel Deployment

This MCP server is configured for serverless deployment on Vercel using Server-Sent Events (SSE).

  1. Push your code to a GitHub repository.

  2. Go to the Vercel Dashboard and create a new project from your repository.

  3. In the environment variables section, add the following variable:

    • Key: GOOGLE_TOKEN_JSON

    • Value: (Paste the exact contents of your local token.json file)

  4. Also add:

    • Key: VERCEL

    • Value: 1

  5. Deploy the project!

Once deployed, your MCP SSE endpoint will be available at: https://<your-vercel-domain>/sse

Clients connecting to a Vercel-deployed server must use the SSE transport configuration instead of the stdio transport.

Testing with MCP Inspector

Use the official MCP Inspector to test your server interactively:

npx -y @modelcontextprotocol/inspector python -m google_mcp_server.server

Running Tests

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src/google_mcp_server --cov-report=term-missing

# Lint
ruff check src/ tests/

Docker

# Build
docker build -f docker/Dockerfile -t google-mcp-server .

# Run (mount your credentials)
docker run -it \
  -v $(pwd)/credentials.json:/app/credentials.json \
  -v $(pwd)/token.json:/app/token.json \
  google-mcp-server

Project Structure

google-mcp-server/
├── pyproject.toml                # Project config & dependencies
├── .env.example                  # Environment variable template
├── credentials.json              # Google OAuth credentials (gitignored)
├── token.json                    # Cached OAuth token (gitignored)
├── src/
│   └── google_mcp_server/
│       ├── server.py             # FastMCP server entry point
│       ├── config.py             # Settings & environment loading
│       ├── auth/
│       │   └── oauth.py          # OAuth 2.0 flow & token management
│       ├── gmail/
│       │   ├── service.py        # Gmail API wrapper functions
│       │   └── tools.py          # Gmail MCP tool definitions
│       ├── docs/
│       │   ├── service.py        # Google Docs API wrapper functions
│       │   └── tools.py          # Docs MCP tool definitions
│       └── utils/
│           └── errors.py         # Error handling & response formatting
├── tests/                        # Unit tests
└── docker/
    └── Dockerfile                # Docker deployment

License

MIT

Available Tools

9 tools
append_to_google_docA

Append content to the end of an existing Google Document.

The content is added after the existing text without overwriting anything.

Args: document_id: The ID of the Google Document to append to. content: The text content to append to the document.

Returns: Document ID, title, number of characters appended, and URL.

Inputs: content (required), document_id (required).

create_google_docA

Create a new Google Document.

Args: title: The title of the new document. content: Optional initial text content to add to the document body.

Returns: Document ID, title, and URL on success, or error details on failure.

Inputs: title (required), content.

draft_emailA

Create a new email draft in Gmail.

Args: to: Recipient email address (comma-separated for multiple recipients). subject: Email subject line. body: Email body content. cc: CC recipients (comma-separated, optional). bcc: BCC recipients (comma-separated, optional). body_type: Content type — "plain" for plain text or "html" for HTML content.

Returns: Draft ID, message ID, and a summary of the created draft.

Inputs: to (required), body (required), subject (required), cc, +2 more.

get_email_draftB

Retrieve an existing email draft from Gmail.

Args: draft_id: The ID of the draft to retrieve.

Returns: Draft details including headers, snippet, and IDs.

Inputs: draft_id (required).

get_google_doc_metadataA

Get metadata for a Google Document.

Retrieves the document's title, revision ID, URL, and page size without reading the full content.

Args: document_id: The ID of the Google Document.

Returns: Document metadata including title, revision, and URL.

Inputs: document_id (required).

read_google_docA

Read the full content of a Google Document.

Extracts all text content from the document, preserving paragraph structure.

Args: document_id: The ID of the Google Document to read (found in the document URL).

Returns: Document ID, title, full text content, and URL.

Inputs: document_id (required).

send_existing_draftB

Send an existing email draft via Gmail.

Args: draft_id: The ID of the draft to send.

Returns: Sent message details or error information.

Inputs: draft_id (required).

send_new_emailA

Send an email directly via Gmail.

This sends the email immediately without creating a draft first.

Args: to: Recipient email address (comma-separated for multiple recipients). subject: Email subject line. body: Email body content. cc: CC recipients (comma-separated, optional). bcc: BCC recipients (comma-separated, optional). body_type: Content type — "plain" for plain text or "html" for HTML content.

Returns: Sent message ID and thread details, or error information.

Inputs: to (required), body (required), subject (required), cc, +2 more.

update_email_draftA

Update an existing email draft in Gmail.

Only provide the fields you want to change — unchanged fields will be preserved from the original draft.

Args: draft_id: The ID of the draft to update. to: New recipient(s), or leave empty to keep existing. subject: New subject, or leave empty to keep existing. body: New body content, or leave empty to keep existing. cc: New CC recipients, or leave empty to keep existing. bcc: New BCC recipients, or leave empty to keep existing. body_type: Content type — "plain" or "html".

Returns: Updated draft details or error information.

Inputs: draft_id (required), cc, to, bcc, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.9/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct action and service (Docs vs. Gmail), with no overlapping purposes. Operations are clearly separated (e.g., draft_email vs. send_new_email, get_google_doc_metadata vs. read_google_doc).

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern (e.g., create_google_doc, draft_email, get_email_draft). No mixing of conventions or vague verbs.

    Tool Count5/5

    9 tools cover core operations for two distinct services (Docs and Gmail). The count is well-scoped, neither too few nor excessive for the stated purpose.

    Completeness3/5

    Core CRUD operations are present for Docs (create, read, append, metadata) but missing update and delete. Gmail covers drafting and sending but lacks listing drafts, deleting, or searching. Notable gaps but not severely incomplete.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Google Workspace MCP Server

      ghratika
      F
      license
      Not graded
      quality
      D
      maintenance
      A complete MCP server integrating Gmail and Google Docs, enabling email management (list, send, search, reply) and document operations (create, edit, search, share) through natural language.
      -

    • Gmail MCP Server

      varun00391
      F
      license
      Not graded
      quality
      D
      maintenance
      Production-ready MCP server for Gmail, enabling AI agents to search, read, send, draft, and manage emails, labels, and attachments via the Google Gmail API.
      -