# 🚀 gworkspace-mcp

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

[![Python](https://img.shields.io/badge/Python-3.12+-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
[![FastMCP](https://img.shields.io/badge/FastMCP-3.4+-FF6B35?style=flat-square)](https://github.com/jlowin/fastmcp)
[![Google APIs](https://img.shields.io/badge/Google%20APIs-Workspace-4285F4?style=flat-square&logo=google&logoColor=white)](https://developers.google.com/workspace)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-SQLAlchemy-336791?style=flat-square&logo=postgresql&logoColor=white)](https://www.postgresql.org/)
[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)

---

## 📖 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

```bash
# 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:**
```bash
# 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

```bash
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`:

```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](LICENSE) for details.

---

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