Server For Gmail & Google Docs

A standalone Model Context Protocol (MCP) server that exposes tools for sending/drafting emails via Gmail and appending content to Google Docs. Built with the official MCP Python SDK using FastMCP.

Features

Tool	Description
gmail_send_email	Send an email immediately via Gmail
gmail_create_draft	Create a draft email (no auto-send)
gdoc_append_content	Append text to an existing Google Doc

• Generic & reusable — works with any MCP-compatible client
• OAuth 2.0 — browser-based consent flow, auto-refresh tokens
• Structured responses — always returns status + IDs or error_message
• Retry logic — exponential backoff on rate limits and server errors
• Secure — credentials never logged, secrets gitignored

Prerequisites

• Python 3.10+
• Google Cloud project with Gmail API and Google Docs API enabled
• OAuth credentials (credentials.json) downloaded from Google Cloud Console

Setup

1. Google Cloud Configuration

1. Go to 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. Go to APIs & Services > OAuth consent screen
   • Set up the consent screen
   • Add your email as a test user
6. Go to APIs & Services > Credentials
   • Click Create Credentials > OAuth client ID
   • Select Desktop app
   • Download the JSON file and save it as credentials.json in the project root

2. Install Dependencies

pip install -r requirements.txt

3. Configure Environment (Optional)

cp .env.example .env
# Edit .env if you need custom paths

Variable	Default	Description
GOOGLE_CREDENTIALS_PATH	./credentials.json	Path to OAuth client secrets
GOOGLE_TOKEN_PATH	./token.json	Path to cached token
LOG_LEVEL	INFO	Logging level

4. First Run (OAuth Consent)

python -m src.server

On the first run, a browser window will open asking you to authorize the app. After granting access, a token.json file will be created and future runs will not require re-authorization.

Usage

Running the Server

python -m src.server

The server communicates over stdio using the MCP protocol.

Connecting from an MCP Client

Antigravity / Claude Desktop

Add to your MCP client configuration:

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

Tool Schemas

gmail_send_email

{
  "to": "[email protected]",
  "subject": "Hello from MCP",
  "body": "This is a test email.",
  "cc": ["[email protected]"],
  "bcc": ["[email protected]"],
  "body_type": "text"
}

Response (success):

{"status": "success", "message_id": "18a1b2c3d4e5f6"}

gmail_create_draft

Same input schema as gmail_send_email.

Response (success):

{"status": "success", "draft_id": "r123456789"}

gdoc_append_content

{
  "document_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
  "content": "Text to append at the end of the document.",
  "add_newline_before": true
}

Response (success):

{"status": "success", "document_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz", "revision_id": "ALm37BWx..."}

Error Response (all tools)

{"status": "error", "error_message": "Document not found: bad_id_123"}

Testing

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=src

Architecture

[Any MCP Client]
      |
      | MCP protocol (stdio)
      v
[MCP Server: google-workspace]
   ├── server.py      → Tool definitions + input validation
   ├── auth.py        → OAuth2 token management + refresh
   ├── gmail_client.py → Gmail API (send, draft)
   ├── gdoc_client.py  → Docs API (append)
   └── config.py      → Environment configuration
      |
      v
[Google Workspace APIs]

Project Structure

MCP-SERVER/
├── requirements.txt        # Python dependencies
├── .env.example            # Environment variable template
├── .gitignore              # Secrets & cache exclusions
├── README.md               # This file
├── credentials.json        # (user-provided, gitignored)
├── token.json              # (auto-generated, gitignored)
├── src/
│   ├── __init__.py
│   ├── server.py           # FastMCP server + tools
│   ├── auth.py             # OAuth2 authentication
│   ├── gmail_client.py     # Gmail API wrapper
│   ├── gdoc_client.py      # Google Docs API wrapper
│   └── config.py           # Configuration loading
└── tests/
    ├── __init__.py
    ├── test_server.py       # Tool + validation tests
    ├── test_gmail_client.py # Gmail client tests
    └── test_gdoc_client.py  # Docs client tests

License

MIT