🚀 gworkspace-mcp

A production-ready Model Context Protocol (MCP) server that gives AI assistants full, authenticated access to the entire Google Workspace ecosystem.

---

📖 Overview

gworkspace-mcp is a Model Context Protocol (MCP) server built with Python that acts as a secure, structured bridge between AI assistants (such as Claude, Cursor, or any MCP-compatible client) and the full suite of Google Workspace services.

Instead of writing one-off Google API scripts, this server exposes all Google Workspace functionality as named, type-safe MCP tools — each with clear docstrings, parameter descriptions, and async support. AI agents can call these tools in natural conversation to read emails, manage Drive files, schedule calendar events, and more, all authenticated against a real Google account.

The server handles the entire OAuth 2.0 lifecycle automatically: first-time browser-based authorization, secure token persistence in PostgreSQL, and silent token refresh using stored refresh tokens — so users never need to re-authenticate.

---

✨ Features

Feature	Description
📧 Gmail	Search, read, send, label, delete emails and download attachments
📁 Google Drive	Search, upload, download, create folders, share, and delete files
📆 Google Calendar	Create, list, update, and delete events with attendees and reminders
✅ Google Tasks	Full task and tasklist management including subtasks
📝 Google Docs	Create, read, append, insert, replace, format text, and insert tables in documents
🔐 OAuth 2.0	Automated first-time browser login with persistent token storage
🔄 Token Refresh	Automatic silent refresh of expired access tokens
🗄️ PostgreSQL Storage	Per-user token persistence using SQLAlchemy ORM
⚡ Async Architecture	All MCP tools are fully async for non-blocking execution

---

🏗️ Architecture

The project follows a clean, layered architecture that separates concerns across four distinct layers:

gworkspace-mcp/
│
├── server.py               # Entry point — initializes FastMCP, registers all tools
├── main.py                 # Minimal demo entry point
├── pyproject.toml          # Project metadata and dependency declarations
│
├── auth/                   # Layer 1: Authentication
│   ├── google_auth.py      # OAuth 2.0 flow (first-time login + credential retrieval)
│   └── token_manager.py    # CRUD operations on the token store (get/save/update/delete)
│
├── db/                     # Layer 2: Persistence
│   ├── database.py         # SQLAlchemy engine, session factory, and Base class
│   └── models.py           # ORM model: Tokens table (email, access_token, refresh_token, expiry)
│
├── services/               # Layer 3: Business Logic
│   ├── gmail_service.py    # Google Gmail API calls (search, read, send, label, delete)
│   ├── drive_service.py    # Google Drive API calls (search, upload, download, share, delete)
│   ├── calendar_service.py # Google Calendar API calls (create, list, update, delete)
│   ├── tasks_service.py    # Google Tasks API calls (tasks, subtasks, tasklists)
│   ├── docs_service.py     # Google Docs API calls (create, read, append, formatting)
│   └── sheets_service.py   # Google Sheets API calls (create, read, write, sheets, formatting)
│
├── tools/                  # Layer 4: MCP Tool Definitions
│   ├── gmail.py            # 7 MCP tools wrapping gmail_service
│   ├── drive.py            # 6 MCP tools wrapping drive_service
│   ├── calendar.py         # 4 MCP tools wrapping calendar_service
│   ├── tasks.py            # 8 MCP tools wrapping tasks_service
│   ├── docs.py             # 8 MCP tools wrapping docs_service
│   └── sheets.py           # 10 MCP tools wrapping sheets_service
│
├── config/                 # Configuration (not committed to source control)
│   ├── credentials.json    # Google OAuth client ID and secret
│   └── .env                # Environment variables (DATABASE_URL, etc.)
│
└── utils/
    └── helpers.py          # Shared utility functions

Data Flow

AI Client (Claude, Cursor, etc.)
        │
        │  MCP Protocol (stdio / SSE)
        ▼
   server.py  ──► FastMCP instance
        │
        ▼
   tools/*.py  ──► MCP tool definitions (@mcp.tool decorator)
        │
        ▼
   services/*.py  ──► Google API business logic
        │              (uses authenticated credentials)
        │
        ├──► auth/google_auth.py  ──► Retrieves or refreshes credentials
        │             │
        │             ▼
        │       auth/token_manager.py  ──► Reads/writes token from DB
        │                    │
        │                    ▼
        │             db/models.py + db/database.py  ──► PostgreSQL
        │
        ▼
   Google Workspace APIs (Gmail, Drive, Calendar, Tasks, ...)

---

🔐 Authentication System

One of the most robust parts of this project is the multi-layer OAuth 2.0 authentication system.

How It Works

1. First-time login: When a user's email is not found in the database, google_auth.py launches a local browser-based OAuth consent flow using InstalledAppFlow. After the user grants consent, the credentials are automatically saved to PostgreSQL.

2. Subsequent calls: On every API call, get_google_credentials(email) looks up the stored token. If the access token is still valid, it is returned immediately. If expired, the refresh token is used to silently obtain a new access token via creds.refresh(Request()), and the updated token is persisted back to the database.

3. Token Storage: Tokens are stored in a tokens table with the user's email as the primary key, along with access_token, refresh_token, scopes, and expiry — all managed through SQLAlchemy.

OAuth Scopes Requested

Scope	Purpose
gmail.modify	Read, send, search, and organize Gmail (without permanent deletion)
drive	Full access to all Google Drive files
calendar.events	View and edit all calendar events
tasks	Create, update, and delete Google Tasks
spreadsheets	Full access to Google Sheets
documents	Full access to Google Docs

---

🛠️ MCP Tools Reference

📧 Gmail Tools

Tool	Description
search_the_gmails	Search Gmail using any query string (e.g. is:unread, from:boss@company.com)
read_the_gmails	Read full email content by message ID — returns body, sender, attachments
get_the_attachment	Download a specific email attachment as base64 by attachment ID
create_the_gmail_label	Create a new custom label for organizing emails
modify_the_gmail_labels	Add or remove labels (including INBOX, SPAM, STARRED) from a message
delete_the_gmails	Delete emails by trash, permanent, or batch strategy
send_the_gmails	Compose and send an email with optional file attachment

📁 Google Drive Tools

Tool	Description
search_the_drive	Search Drive files/folders by name, MIME type, or any Drive query
upload_to_the_drive	Upload a single file or recursively upload an entire folder
create_the_folder	Create a new Drive folder with optional parent folder
download_from_drive	Download a Drive file to a local path
share_the_file	Share a file with a user, group, domain, or make it public with role control
delete_the_drive_file	Move a file to trash or permanently delete it

📆 Google Calendar Tools

Tool	Description
create_calender_events	Create an event with title, time, location, guests, and reminders
list_calender_events	List events within a date range, up to a configurable max
update_calender_event	Update any field of an existing event
delete_calender_event	Delete an event by its ID

✅ Google Tasks Tools

Tool	Description
create_the_tasklist	Create a new named task list
create_the_task	Create a task with title, notes, and due date
create_the_subtask	Create a subtask nested under an existing parent task
update_the_task	Update a task's title, notes, due date, or status (needsAction / completed)
list_the_tasks	List tasks with filters (completed, hidden, due date, updated date)
list_the_tasklists	List all task lists for the authenticated user
delete_the_task	Permanently delete a task or subtask (cascades to subtasks)
delete_the_tasklists	Permanently delete an entire task list and all its tasks

📝 Google Docs Tools

Tool	Description
create_the_document	Create a new blank Google Document with a title
read_the_document	Retrieve the full content and metadata of a Google Document by ID
append_the_document	Append text at the end of a Google Document
insert_the_document_text	Insert text at a specific character index in a Document
replace_the_document_text	Find and replace all occurrences of a text string in a Document
delete_the_document_content	Delete content between two character index positions
format_the_document_text	Apply formatting (bold, italic, underline, font size, color) to text
insert_the_document_table	Insert an empty table with specified rows and columns

---

🚀 Getting Started

Prerequisites

• Python 3.12+
• A PostgreSQL database instance
• A Google Cloud Project with the following APIs enabled:
  • Gmail API
  • Google Drive API
  • Google Calendar API
  • Google Tasks API
  • Google Docs API
  • Google Sheets API
• An OAuth 2.0 Client ID (Desktop app type) downloaded as credentials.json

Installation

# Clone the repository
git clone https://github.com/your-username/gworkspace-mcp.git
cd gworkspace-mcp

# Option 1: Using pip (editable install)
pip install -e .

# Option 2: Using uv (recommended)
uv sync

Configuration

1. Place your Google credentials:

config/credentials.json   ← your OAuth 2.0 client secret JSON from Google Cloud Console

2. Create the environment file:

# config/.env
DATABASE_URL=postgresql://user:password@localhost:5432/gworkspace_mcp

3. (First run only) A browser window will open asking you to authorize with your Google account. After authorization, tokens are stored in the database automatically.

Running the Server

python server.py

The MCP server will start and listen for connections from any MCP-compatible client.

Connecting to an MCP Client

To connect this server to Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "gworkspace": {
      "command": "python",
      "args": ["C:/path/to/gworkspace-mcp/server.py"]
    }
  }
}

---

🧩 Tech Stack

Technology	Role
Python 3.12+	Core language
FastMCP 3.4+	MCP server framework — tool registration and protocol handling
Google API Python Client	Official Google Workspace API client library
google-auth / google-auth-oauthlib	OAuth 2.0 credential management and token refresh
SQLAlchemy 2.0	ORM for database models and session management
PostgreSQL	Persistent storage for OAuth tokens
psycopg2-binary / asyncpg	PostgreSQL drivers (sync + async)
python-dotenv	Environment variable loading from .env file

---

📌 Project Status

Component	Status
Gmail (tools + service)	✅ Complete
Google Drive (tools + service)	✅ Complete
Google Calendar (tools + service)	✅ Complete
Google Tasks (tools + service)	✅ Complete
OAuth 2.0 + Token Management	✅ Complete
PostgreSQL Token Persistence	✅ Complete
Google Docs (tools + service)	✅ Complete
Google Sheets (tools + service)	✅ Complete
Automated Tests	📋 Planned
Docker Support	📋 Planned

---

🛣️ Roadmap

• [x] Complete Google Docs service (create, read, update documents)
• [x] Complete Google Sheets service (read, write, format, rows/columns manipulation)
• [ ] Add comprehensive pytest test suite
• [ ] Add Docker + Docker Compose setup for easy deployment
• [ ] Add multi-user support with user session isolation
• [ ] Add rate limiting and error retry logic
• [ ] Publish to PyPI as an installable MCP server package

---

🤝 Contributing

Contributions are welcome! Please open an issue first to discuss any significant changes. Make sure to:

1. Follow the existing layered architecture (tools → services → auth/db)
2. Add proper docstrings to all new MCP tool functions
3. Test with a real Google account before submitting

---

⚠️ Security Notice

• Never commit config/credentials.json or config/.env to version control.
• Both files are listed in .gitignore by default.
• OAuth tokens are stored in the database — ensure your PostgreSQL instance is secured appropriately.

---

📄 License

This project is licensed under the MIT License. See LICENSE for details.

---

<p align="center"> Built with ❤️ using <strong>FastMCP</strong> and the <strong>Google Workspace APIs</strong> </p>