gsuite-mcp 0.4.0__tar.gz

gsuite_mcp-0.4.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: gsuite-mcp
+Version: 0.4.0
+Summary: MCP server for Google Workspace (Gmail, Calendar, Drive, Sheets, Tasks, Contacts), built on gsuite-sdk
+Author-email: Pablo Alaniz <alanizpablo@gmail.com>
+License: MIT
+Project-URL: Homepage, https://pabloalaniz.github.io/google-suite/
+Project-URL: Repository, https://github.com/PabloAlaniz/google-suite
+Keywords: mcp,model-context-protocol,google-workspace,gmail,google-sheets,agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: gsuite-sdk>=0.3.0
+Requires-Dist: mcp<3,>=2.3
+
+# gsuite-mcp
+
+<!-- mcp-name: io.github.PabloAlaniz/gsuite-sdk -->
+
+An [MCP](https://modelcontextprotocol.io) server for Google Workspace: Gmail,
+Calendar, Drive, Sheets, Tasks and Contacts, built on
+[gsuite-sdk](https://pypi.org/project/gsuite-sdk/). It runs locally over stdio
+and uses your own Google login.
+
+## Setup
+
+1. Get an OAuth client file from Google Cloud
+   ([guide](https://pabloalaniz.github.io/google-suite/GETTING_CREDENTIALS/))
+   and log in once with the gsuite CLI:
+
+   ```bash
+   pip install "gsuite-sdk[cli]"
+   gsuite auth login                                   # Gmail, Calendar, Drive, Sheets
+   gsuite auth login --force --scopes default,tasks,contacts   # + Tasks and Contacts
+   ```
+
+   The token is saved to `tokens.db` in the current directory (or
+   `GSUITE_TOKEN_DB_PATH`).
+
+2. Add the server to your MCP client, pointing at that token with absolute
+   paths:
+
+   ```json
+   {
+     "mcpServers": {
+       "gsuite": {
+         "command": "uvx",
+         "args": ["gsuite-mcp"],
+         "env": {
+           "GSUITE_TOKEN_DB_PATH": "/Users/you/gsuite/tokens.db",
+           "GSUITE_CREDENTIALS_FILE": "/Users/you/gsuite/credentials.json",
+           "GSUITE_DEFAULT_TIMEZONE": "America/Argentina/Buenos_Aires"
+         }
+       }
+     }
+   }
+   ```
+
+   Claude Code: `claude mcp add gsuite -e GSUITE_TOKEN_DB_PATH=/Users/you/gsuite/tokens.db -- uvx gsuite-mcp`
+
+## Tools
+
+| Area | Tools |
+|---|---|
+| Account | `auth_status` |
+| Gmail | `gmail_search`, `gmail_read`, `gmail_send`, `gmail_reply`, `gmail_create_draft` |
+| Calendar | `calendar_list_events`, `calendar_create_event`, `calendar_delete_event`, `calendar_free_busy` |
+| Drive | `drive_search`, `drive_read_file`, `drive_upload`, `drive_share` |
+| Sheets | `sheets_read`, `sheets_append`, `sheets_update`, `sheets_upsert` |
+| Tasks | `tasks_list`, `tasks_add`, `tasks_complete` |
+| Contacts | `contacts_search`, `contacts_get` |
+
+Read tools are annotated read-only; tools that send, share, overwrite or
+delete are marked so clients can ask before running them. Dates are ISO 8601;
+times without an offset use `GSUITE_DEFAULT_TIMEZONE` (UTC by default).
+
+The same capabilities are available as an [agent skill](https://github.com/PabloAlaniz/google-suite/tree/main/skills/gsuite-sdk),
+a CLI and a REST API: see [gsuite-sdk](https://pabloalaniz.github.io/google-suite/).
+
+## License
+
+MIT

gsuite_mcp-0.4.0/README.md

@@ -0,0 +1,67 @@
+# gsuite-mcp
+
+<!-- mcp-name: io.github.PabloAlaniz/gsuite-sdk -->
+
+An [MCP](https://modelcontextprotocol.io) server for Google Workspace: Gmail,
+Calendar, Drive, Sheets, Tasks and Contacts, built on
+[gsuite-sdk](https://pypi.org/project/gsuite-sdk/). It runs locally over stdio
+and uses your own Google login.
+
+## Setup
+
+1. Get an OAuth client file from Google Cloud
+   ([guide](https://pabloalaniz.github.io/google-suite/GETTING_CREDENTIALS/))
+   and log in once with the gsuite CLI:
+
+   ```bash
+   pip install "gsuite-sdk[cli]"
+   gsuite auth login                                   # Gmail, Calendar, Drive, Sheets
+   gsuite auth login --force --scopes default,tasks,contacts   # + Tasks and Contacts
+   ```
+
+   The token is saved to `tokens.db` in the current directory (or
+   `GSUITE_TOKEN_DB_PATH`).
+
+2. Add the server to your MCP client, pointing at that token with absolute
+   paths:
+
+   ```json
+   {
+     "mcpServers": {
+       "gsuite": {
+         "command": "uvx",
+         "args": ["gsuite-mcp"],
+         "env": {
+           "GSUITE_TOKEN_DB_PATH": "/Users/you/gsuite/tokens.db",
+           "GSUITE_CREDENTIALS_FILE": "/Users/you/gsuite/credentials.json",
+           "GSUITE_DEFAULT_TIMEZONE": "America/Argentina/Buenos_Aires"
+         }
+       }
+     }
+   }
+   ```
+
+   Claude Code: `claude mcp add gsuite -e GSUITE_TOKEN_DB_PATH=/Users/you/gsuite/tokens.db -- uvx gsuite-mcp`
+
+## Tools
+
+| Area | Tools |
+|---|---|
+| Account | `auth_status` |
+| Gmail | `gmail_search`, `gmail_read`, `gmail_send`, `gmail_reply`, `gmail_create_draft` |
+| Calendar | `calendar_list_events`, `calendar_create_event`, `calendar_delete_event`, `calendar_free_busy` |
+| Drive | `drive_search`, `drive_read_file`, `drive_upload`, `drive_share` |
+| Sheets | `sheets_read`, `sheets_append`, `sheets_update`, `sheets_upsert` |
+| Tasks | `tasks_list`, `tasks_add`, `tasks_complete` |
+| Contacts | `contacts_search`, `contacts_get` |
+
+Read tools are annotated read-only; tools that send, share, overwrite or
+delete are marked so clients can ask before running them. Dates are ISO 8601;
+times without an offset use `GSUITE_DEFAULT_TIMEZONE` (UTC by default).
+
+The same capabilities are available as an [agent skill](https://github.com/PabloAlaniz/google-suite/tree/main/skills/gsuite-sdk),
+a CLI and a REST API: see [gsuite-sdk](https://pabloalaniz.github.io/google-suite/).
+
+## License
+
+MIT

gsuite_mcp-0.4.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gsuite-mcp"
+version = "0.4.0"
+description = "MCP server for Google Workspace (Gmail, Calendar, Drive, Sheets, Tasks, Contacts), built on gsuite-sdk"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+authors = [
+    {name = "Pablo Alaniz", email = "alanizpablo@gmail.com"}
+]
+keywords = ["mcp", "model-context-protocol", "google-workspace", "gmail", "google-sheets", "agents"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Communications :: Email",
+    "Topic :: Office/Business",
+]
+dependencies = [
+    "gsuite-sdk>=0.3.0",
+    "mcp>=2.3,<3",
+]
+
+[project.scripts]
+gsuite-mcp = "gsuite_mcp.server:main"
+
+[project.urls]
+Homepage = "https://pabloalaniz.github.io/google-suite/"
+Repository = "https://github.com/PabloAlaniz/google-suite"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["gsuite_mcp*"]
+
+[tool.setuptools.package-data]
+gsuite_mcp = ["py.typed"]
+
+[tool.uv.sources]
+gsuite-sdk = { workspace = true }

gsuite_mcp-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gsuite_mcp-0.4.0/src/gsuite_mcp/__init__.py

@@ -0,0 +1,12 @@
+"""Google Suite MCP - Model Context Protocol server for gsuite-sdk."""
+
+__version__ = "0.1.0"
+
+from gsuite_mcp.server import build_server, main
+from gsuite_mcp.services import Services
+
+__all__ = [
+    "build_server",
+    "main",
+    "Services",
+]

gsuite_mcp-0.4.0/src/gsuite_mcp/serialize.py

@@ -0,0 +1,55 @@
+"""SDK entities as JSON-ready dicts for tool results."""
+
+from __future__ import annotations
+
+import dataclasses
+from datetime import date, datetime
+from typing import Any
+
+# Bulky or internal fields agents don't need
+SKIP = {"raw", "html", "plain", "messages", "references"}
+
+
+def to_json(value: Any, *, skip: set[str] = SKIP) -> Any:
+    """Dataclasses become dicts (minus raw/private fields), dates become ISO strings."""
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return {
+            f.name: to_json(getattr(value, f.name), skip=skip)
+            for f in dataclasses.fields(value)
+            if not f.name.startswith("_") and f.name not in skip
+        }
+    if isinstance(value, datetime | date):
+        return value.isoformat()
+    if isinstance(value, dict):
+        return {str(k): to_json(v, skip=skip) for k, v in value.items()}
+    if isinstance(value, list | tuple | set):
+        return [to_json(v, skip=skip) for v in value]
+    return value
+
+
+def message_summary(message: Any) -> dict[str, Any]:
+    """A Gmail message without its body: what a search result needs."""
+    return {
+        "id": message.id,
+        "thread_id": message.thread_id,
+        "subject": message.subject,
+        "sender": message.sender,
+        "date": to_json(message.date),
+        "snippet": message.snippet,
+        "labels": list(message.labels),
+        "attachments": [a.filename for a in message.attachments],
+    }
+
+
+def message_full(message: Any) -> dict[str, Any]:
+    """A Gmail message with its text body and attachment metadata."""
+    return {
+        **message_summary(message),
+        "recipient": message.recipient,
+        "cc": message.cc,
+        "body": message.body,
+        "attachments": [
+            {"id": a.id, "filename": a.filename, "mime_type": a.mime_type, "size": a.size}
+            for a in message.attachments
+        ],
+    }

gsuite_mcp-0.4.0/src/gsuite_mcp/server.py

@@ -0,0 +1,412 @@
+"""MCP server for gsuite-sdk: Gmail, Calendar, Drive, Sheets, Tasks and Contacts tools.
+
+Runs over stdio (``gsuite-mcp``) and reuses the login of ``gsuite auth login``
+(GSUITE_TOKEN_DB_PATH / GSUITE_CREDENTIALS_FILE). Tools are annotated so
+clients can tell read-only ones from those that send, share or delete.
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from datetime import date, datetime
+from typing import Any, Literal, TypeVar
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.types import ToolAnnotations
+
+from gsuite_core import __version__
+from gsuite_core.exceptions import GSuiteError, PermissionDeniedError
+from gsuite_mcp.serialize import message_full, message_summary, to_json
+from gsuite_mcp.services import Services
+
+INSTRUCTIONS = """\
+Google Workspace for the signed-in user: Gmail, Calendar, Drive, Sheets, Tasks
+and Contacts. Read tools are safe to call freely. Ask the user before tools
+that send email, invite attendees, share files or delete anything. Dates are
+ISO 8601 (2026-03-01 or 2026-03-01T10:00); times without an offset use the
+server's GSUITE_DEFAULT_TIMEZONE (UTC by default). If a tool says there is no
+login, tell the user to run `gsuite auth login`."""
+
+READ = ToolAnnotations(read_only_hint=True, open_world_hint=True)
+WRITE = ToolAnnotations(read_only_hint=False, destructive_hint=False, open_world_hint=True)
+DESTRUCTIVE = ToolAnnotations(read_only_hint=False, destructive_hint=True, open_world_hint=True)
+
+SendUpdates = Literal["all", "externalOnly", "none"]
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def sdk_errors(func: F) -> F:
+    """SDK errors become tool errors the agent can read."""
+
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return func(*args, **kwargs)
+        except ToolError:
+            raise
+        except PermissionDeniedError as exc:
+            raise ToolError(
+                f"{exc.message}. Usually a scope missing from the login: run "
+                "`gsuite auth login --force --scopes default,tasks,contacts`."
+            ) from exc
+        except GSuiteError as exc:
+            raise ToolError(f"{type(exc).__name__}: {exc.message}") from exc
+        except ValueError as exc:
+            raise ToolError(str(exc)) from exc
+
+    return wrapper  # type: ignore[return-value]
+
+
+def results(items: list[Any]) -> dict[str, Any]:
+    """One object for list results (a bare list becomes one content block per item)."""
+    return {"count": len(items), "results": items}
+
+
+def parse_when(value: str) -> datetime | date:
+    """ "2026-03-01" -> date; "2026-03-01T10:00" / "2026-03-01 10:00" -> datetime."""
+    try:
+        if len(value) == 10:
+            return date.fromisoformat(value)
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise ToolError(f"{value!r} is not an ISO date or datetime") from exc
+
+
+def parse_day(value: str | None) -> date | None:
+    if value is None:
+        return None
+    when = parse_when(value)
+    return when.date() if isinstance(when, datetime) else when
+
+
+def build_server(services: Services | None = None) -> MCPServer:
+    """The MCP server; tests pass Services built on mocked clients."""
+    svc = services or Services()
+    server = MCPServer(
+        "gsuite-sdk",
+        title="Google Workspace (gsuite-sdk)",
+        instructions=INSTRUCTIONS,
+        version=__version__,
+        website_url="https://pabloalaniz.github.io/google-suite/",
+    )
+
+    def tool(annotations: ToolAnnotations) -> Callable[[F], F]:
+        def register(func: F) -> F:
+            server.tool(annotations=annotations)(sdk_errors(func))
+            return func
+
+        return register
+
+    # ------------------------------------------------------------- auth
+
+    @tool(READ)
+    def auth_status() -> dict[str, Any]:
+        """Whether the server has a valid Google login, and for which account and scopes."""
+        auth = svc.auth()
+        credentials = auth.credentials
+        return {
+            "authenticated": True,
+            "email": auth.get_user_email(),
+            "scopes": sorted(credentials.scopes or []) if credentials else [],
+        }
+
+    # ------------------------------------------------------------ gmail
+
+    @tool(READ)
+    def gmail_search(query: str, max_results: int = 10) -> dict[str, Any]:
+        """Search Gmail with Gmail query syntax (from:, to:, subject:, is:unread,
+        has:attachment, newer_than:7d, label:...). Returns summaries without bodies."""
+        return results(
+            [message_summary(m) for m in svc.gmail.search(query, max_results=max_results)]
+        )
+
+    @tool(READ)
+    def gmail_read(message_id: str) -> dict[str, Any]:
+        """Read one email: headers, text body and attachment list."""
+        message = svc.gmail.get_message(message_id)
+        if message is None:
+            raise ToolError(f"No message {message_id}")
+        return message_full(message)
+
+    @tool(WRITE)
+    def gmail_send(
+        to: list[str],
+        subject: str,
+        body: str,
+        cc: list[str] | None = None,
+        bcc: list[str] | None = None,
+        html: bool = False,
+    ) -> dict[str, Any]:
+        """Send an email. Confirm recipients and content with the user first."""
+        sent = svc.gmail.send(to=to, subject=subject, body=body, cc=cc, bcc=bcc, html=html)
+        return {"id": sent.id, "thread_id": sent.thread_id}
+
+    @tool(WRITE)
+    def gmail_reply(message_id: str, body: str, reply_all: bool = False) -> dict[str, Any]:
+        """Reply in the thread of a message. Confirm the content with the user first."""
+        message = svc.gmail.get_message(message_id)
+        if message is None:
+            raise ToolError(f"No message {message_id}")
+        sent = svc.gmail.reply(message, body, reply_all=reply_all)
+        return {"id": sent.id, "thread_id": sent.thread_id}
+
+    @tool(WRITE)
+    def gmail_create_draft(
+        to: list[str], subject: str, body: str, cc: list[str] | None = None
+    ) -> dict[str, Any]:
+        """Save a draft without sending it (safe way to propose an email)."""
+        draft = svc.gmail.create_draft(to=to, subject=subject, body=body, cc=cc)
+        return {"draft_id": draft.id}
+
+    # --------------------------------------------------------- calendar
+
+    @tool(READ)
+    def calendar_list_events(
+        days: int = 7, calendar_id: str | None = None, max_results: int = 50
+    ) -> dict[str, Any]:
+        """Events from now until `days` ahead."""
+        events = svc.calendar.get_upcoming(
+            days=days, calendar_id=calendar_id, max_results=max_results
+        )
+        return results(to_json(events))
+
+    @tool(WRITE)
+    def calendar_create_event(
+        summary: str,
+        start: str,
+        end: str | None = None,
+        description: str | None = None,
+        location: str | None = None,
+        attendees: list[str] | None = None,
+        meet: bool = False,
+        send_updates: SendUpdates = "none",
+        calendar_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Create an event. `start`/`end` are ISO; a date alone makes an all-day event.
+        `meet` adds a Google Meet link; `send_updates="all"` emails the attendees
+        (confirm with the user first)."""
+        start_at = parse_when(start)
+        event = svc.calendar.create_event(
+            summary=summary,
+            start=start_at,
+            end=parse_when(end) if end else None,
+            description=description,
+            location=location,
+            attendees=attendees,
+            all_day=not isinstance(start_at, datetime),
+            meet=meet,
+            send_updates=send_updates,
+            calendar_id=calendar_id,
+        )
+        return to_json(event)  # type: ignore[no-any-return]
+
+    @tool(DESTRUCTIVE)
+    def calendar_delete_event(
+        event_id: str, send_updates: SendUpdates = "none", calendar_id: str | None = None
+    ) -> dict[str, Any]:
+        """Delete an event. Confirm with the user first."""
+        deleted = svc.calendar.delete_event(
+            event_id, calendar_id=calendar_id, send_updates=send_updates
+        )
+        if not deleted:
+            raise ToolError(f"No event {event_id}")
+        return {"deleted": event_id}
+
+    @tool(READ)
+    def calendar_free_busy(
+        time_min: str, time_max: str, calendars: list[str] | None = None
+    ) -> dict[str, Any]:
+        """Busy intervals per calendar (default: the user's) between two ISO datetimes."""
+        start, end = parse_when(time_min), parse_when(time_max)
+        if not (isinstance(start, datetime) and isinstance(end, datetime)):
+            raise ToolError("time_min and time_max need a time, e.g. 2026-03-02T09:00")
+        return to_json(svc.calendar.get_free_busy(start, end, calendars=calendars))  # type: ignore[no-any-return]
+
+    # ------------------------------------------------------------ drive
+
+    @tool(READ)
+    def drive_search(
+        name: str | None = None, query: str | None = None, max_results: int = 20
+    ) -> dict[str, Any]:
+        """Find files by name (contains) or with a raw Drive query
+        (e.g. "mimeType = 'application/pdf' and modifiedTime > '2026-01-01'")."""
+        if name and not query:
+            files = svc.drive.search(name)[:max_results]
+        else:
+            files = svc.drive.list_files(query=query, max_results=max_results)
+        return results(to_json(files))
+
+    @tool(READ)
+    def drive_read_file(file_id: str, max_chars: int = 20000) -> dict[str, Any]:
+        """Text of a file: Google Docs/Slides as text, Google Sheets as CSV, and
+        plain-text files as they are. Binary files (PDF, images) are refused."""
+        file = svc.drive.get(file_id)
+        if file is None:
+            raise ToolError(f"No file {file_id}")
+        mime = file.mime_type
+        if mime == "application/vnd.google-apps.spreadsheet":
+            text = svc.drive.export(file_id, "csv").decode("utf-8", "replace")
+        elif mime.startswith("application/vnd.google-apps."):
+            text = svc.drive.export(file_id, "txt").decode("utf-8", "replace")
+        elif mime.startswith("text/") or mime in ("application/json", "application/xml"):
+            text = svc.drive.get_content(file_id).decode("utf-8", "replace")
+        else:
+            raise ToolError(
+                f"{file.name} is {mime}, not text. Download it with "
+                f"`gsuite drive download {file_id}` instead."
+            )
+        return {
+            "id": file.id,
+            "name": file.name,
+            "mime_type": mime,
+            "truncated": len(text) > max_chars,
+            "text": text[:max_chars],
+        }
+
+    @tool(WRITE)
+    def drive_upload(
+        path: str, parent_id: str | None = None, name: str | None = None
+    ) -> dict[str, Any]:
+        """Upload a local file (path on the machine running this server)."""
+        return to_json(svc.drive.upload(path, name=name, parent_id=parent_id))  # type: ignore[no-any-return]
+
+    @tool(WRITE)
+    def drive_share(
+        file_id: str,
+        email: str | None = None,
+        role: Literal["reader", "commenter", "writer"] = "reader",
+        anyone: bool = False,
+        notify: bool = True,
+    ) -> dict[str, Any]:
+        """Share a file with a person (email) or with anyone who has the link
+        (anyone=true). Confirm with the user first."""
+        if not email and not anyone:
+            raise ToolError("Give an email, or anyone=true for a link anyone can open")
+        permission = svc.drive.add_permission(
+            file_id,
+            role=role,
+            type="anyone" if anyone else "user",
+            email=email,
+            notify=notify,
+        )
+        return to_json(permission)  # type: ignore[no-any-return]
+
+    # ----------------------------------------------------------- sheets
+
+    def open_spreadsheet(spreadsheet: str) -> Any:
+        """By URL, ID or exact title."""
+        if spreadsheet.startswith("http"):
+            return svc.sheets.open_by_url(spreadsheet)
+        if len(spreadsheet) > 30:
+            return svc.sheets.open_by_key(spreadsheet)
+        return svc.sheets.open(spreadsheet)
+
+    def worksheet(spreadsheet: str, sheet: str | None) -> Any:
+        doc = open_spreadsheet(spreadsheet)
+        ws = doc.worksheet(sheet) if sheet else doc.sheet1
+        if ws is None:
+            raise ToolError(f"No tab {sheet!r} in {doc.title}")
+        return ws
+
+    @tool(READ)
+    def sheets_read(
+        spreadsheet: str, range: str = "A1:Z200", sheet: str | None = None
+    ) -> dict[str, Any]:
+        """Read a range. `spreadsheet` is a URL, an ID or an exact title; `sheet`
+        is the tab (default: the first one). Values come back as displayed."""
+        ws = worksheet(spreadsheet, sheet)
+        return {"sheet": ws.title, "range": range, "values": ws.get(range)}
+
+    @tool(WRITE)
+    def sheets_append(
+        spreadsheet: str, rows: list[list[Any]], sheet: str | None = None
+    ) -> dict[str, Any]:
+        """Append rows after the last one with data."""
+        ws = worksheet(spreadsheet, sheet)
+        ws.append_rows(rows)
+        return {"sheet": ws.title, "appended": len(rows)}
+
+    @tool(DESTRUCTIVE)
+    def sheets_update(
+        spreadsheet: str, range: str, values: list[list[Any]], sheet: str | None = None
+    ) -> dict[str, Any]:
+        """Overwrite a range starting at `range` (e.g. "B2") with a 2D list of values."""
+        ws = worksheet(spreadsheet, sheet)
+        ws.update(range, values)
+        return {"sheet": ws.title, "range": range, "rows": len(values)}
+
+    @tool(WRITE)
+    def sheets_upsert(
+        spreadsheet: str, rows: list[dict[str, Any]], key: str, sheet: str | None = None
+    ) -> dict[str, Any]:
+        """Update the rows whose `key` column matches and append the rest.
+        The first row of the sheet is the header; rows are {column: value}."""
+        ws = worksheet(spreadsheet, sheet)
+        return dict(ws.upsert(rows, key=key))
+
+    # ------------------------------------------------------------ tasks
+
+    @tool(READ)
+    def tasks_list(
+        tasklist_id: str = "@default",
+        show_completed: bool = False,
+        due_before: str | None = None,
+        max_results: int = 100,
+    ) -> dict[str, Any]:
+        """Tasks of a list (default: the user's main list), pending only unless
+        show_completed. Needs the Tasks scope."""
+        tasks = svc.tasks.list_tasks(
+            tasklist_id,
+            show_completed=show_completed,
+            due_max=parse_day(due_before),
+            max_results=max_results,
+        )
+        return results(to_json(tasks))
+
+    @tool(WRITE)
+    def tasks_add(
+        title: str,
+        notes: str | None = None,
+        due: str | None = None,
+        tasklist_id: str = "@default",
+        parent: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a task (a subtask when `parent` is a task ID). `due` is a day."""
+        task = svc.tasks.create_task(
+            title, notes=notes, due=parse_day(due), tasklist_id=tasklist_id, parent=parent
+        )
+        return to_json(task)  # type: ignore[no-any-return]
+
+    @tool(WRITE)
+    def tasks_complete(task_id: str, tasklist_id: str = "@default") -> dict[str, Any]:
+        """Mark a task as completed."""
+        return to_json(svc.tasks.complete_task(task_id, tasklist_id=tasklist_id))  # type: ignore[no-any-return]
+
+    # --------------------------------------------------------- contacts
+
+    @tool(READ)
+    def contacts_search(query: str, max_results: int = 10) -> dict[str, Any]:
+        """Contacts whose name, email, phone or company starts with `query`
+        (max 30). Needs the Contacts scope."""
+        return results(to_json(svc.contacts.search(query, max_results=max_results)))
+
+    @tool(READ)
+    def contacts_get(contact_id: str) -> dict[str, Any]:
+        """One contact by ID ("c123" or "people/c123")."""
+        contact = svc.contacts.get(contact_id)
+        if contact is None:
+            raise ToolError(f"No contact {contact_id}")
+        return to_json(contact)  # type: ignore[no-any-return]
+
+    return server
+
+
+def main() -> None:
+    """Console entry point: `gsuite-mcp` serves over stdio."""
+    build_server().run("stdio")
+
+
+if __name__ == "__main__":
+    main()

gsuite_mcp-0.4.0/src/gsuite_mcp/services.py

@@ -0,0 +1,84 @@
+"""Lazily built SDK clients sharing one GoogleAuth, and the login check."""
+
+from __future__ import annotations
+
+from functools import cached_property
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from mcp.server.mcpserver.exceptions import ToolError
+
+from gsuite_core import GoogleAuth, get_settings
+
+if TYPE_CHECKING:
+    from gsuite_calendar import Calendar
+    from gsuite_contacts import Contacts
+    from gsuite_drive import Drive
+    from gsuite_gmail import Gmail
+    from gsuite_sheets import Sheets
+    from gsuite_tasks import Tasks
+
+
+def login_hint() -> str:
+    settings = get_settings()
+    token_db = Path(settings.token_db_path).resolve()
+    return (
+        f"No valid Google login in {token_db}. Run `gsuite auth login` (add "
+        "`--scopes default,tasks,contacts` for Tasks and Contacts) in the directory "
+        "this server runs from, or set GSUITE_TOKEN_DB_PATH and GSUITE_CREDENTIALS_FILE "
+        "to absolute paths in the server's configuration."
+    )
+
+
+class Services:
+    """One GoogleAuth for every client; clients are created on first use."""
+
+    def __init__(self, auth: Any = None) -> None:
+        self._auth = auth
+
+    def auth(self) -> Any:
+        if self._auth is None:
+            self._auth = GoogleAuth()
+        auth = self._auth
+        if auth.is_authenticated():
+            return auth
+        if auth.needs_refresh():
+            auth.refresh()
+            return auth
+        raise ToolError(login_hint())
+
+    @cached_property
+    def gmail(self) -> Gmail:
+        from gsuite_gmail import Gmail
+
+        return Gmail(self.auth())
+
+    @cached_property
+    def calendar(self) -> Calendar:
+        from gsuite_calendar import Calendar
+
+        return Calendar(self.auth())
+
+    @cached_property
+    def drive(self) -> Drive:
+        from gsuite_drive import Drive
+
+        return Drive(self.auth())
+
+    @cached_property
+    def sheets(self) -> Sheets:
+        from gsuite_sheets import Sheets
+
+        return Sheets(self.auth())
+
+    @cached_property
+    def tasks(self) -> Tasks:
+        from gsuite_tasks import Tasks
+
+        return Tasks(self.auth())
+
+    @cached_property
+    def contacts(self) -> Contacts:
+        from gsuite_contacts import Contacts
+
+        return Contacts(self.auth())

gsuite_mcp-0.4.0/src/gsuite_mcp.egg-info/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: gsuite-mcp
+Version: 0.4.0
+Summary: MCP server for Google Workspace (Gmail, Calendar, Drive, Sheets, Tasks, Contacts), built on gsuite-sdk
+Author-email: Pablo Alaniz <alanizpablo@gmail.com>
+License: MIT
+Project-URL: Homepage, https://pabloalaniz.github.io/google-suite/
+Project-URL: Repository, https://github.com/PabloAlaniz/google-suite
+Keywords: mcp,model-context-protocol,google-workspace,gmail,google-sheets,agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: gsuite-sdk>=0.3.0
+Requires-Dist: mcp<3,>=2.3
+
+# gsuite-mcp
+
+<!-- mcp-name: io.github.PabloAlaniz/gsuite-sdk -->
+
+An [MCP](https://modelcontextprotocol.io) server for Google Workspace: Gmail,
+Calendar, Drive, Sheets, Tasks and Contacts, built on
+[gsuite-sdk](https://pypi.org/project/gsuite-sdk/). It runs locally over stdio
+and uses your own Google login.
+
+## Setup
+
+1. Get an OAuth client file from Google Cloud
+   ([guide](https://pabloalaniz.github.io/google-suite/GETTING_CREDENTIALS/))
+   and log in once with the gsuite CLI:
+
+   ```bash
+   pip install "gsuite-sdk[cli]"
+   gsuite auth login                                   # Gmail, Calendar, Drive, Sheets
+   gsuite auth login --force --scopes default,tasks,contacts   # + Tasks and Contacts
+   ```
+
+   The token is saved to `tokens.db` in the current directory (or
+   `GSUITE_TOKEN_DB_PATH`).
+
+2. Add the server to your MCP client, pointing at that token with absolute
+   paths:
+
+   ```json
+   {
+     "mcpServers": {
+       "gsuite": {
+         "command": "uvx",
+         "args": ["gsuite-mcp"],
+         "env": {
+           "GSUITE_TOKEN_DB_PATH": "/Users/you/gsuite/tokens.db",
+           "GSUITE_CREDENTIALS_FILE": "/Users/you/gsuite/credentials.json",
+           "GSUITE_DEFAULT_TIMEZONE": "America/Argentina/Buenos_Aires"
+         }
+       }
+     }
+   }
+   ```
+
+   Claude Code: `claude mcp add gsuite -e GSUITE_TOKEN_DB_PATH=/Users/you/gsuite/tokens.db -- uvx gsuite-mcp`
+
+## Tools
+
+| Area | Tools |
+|---|---|
+| Account | `auth_status` |
+| Gmail | `gmail_search`, `gmail_read`, `gmail_send`, `gmail_reply`, `gmail_create_draft` |
+| Calendar | `calendar_list_events`, `calendar_create_event`, `calendar_delete_event`, `calendar_free_busy` |
+| Drive | `drive_search`, `drive_read_file`, `drive_upload`, `drive_share` |
+| Sheets | `sheets_read`, `sheets_append`, `sheets_update`, `sheets_upsert` |
+| Tasks | `tasks_list`, `tasks_add`, `tasks_complete` |
+| Contacts | `contacts_search`, `contacts_get` |
+
+Read tools are annotated read-only; tools that send, share, overwrite or
+delete are marked so clients can ask before running them. Dates are ISO 8601;
+times without an offset use `GSUITE_DEFAULT_TIMEZONE` (UTC by default).
+
+The same capabilities are available as an [agent skill](https://github.com/PabloAlaniz/google-suite/tree/main/skills/gsuite-sdk),
+a CLI and a REST API: see [gsuite-sdk](https://pabloalaniz.github.io/google-suite/).
+
+## License
+
+MIT

gsuite_mcp-0.4.0/src/gsuite_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+src/gsuite_mcp/__init__.py
+src/gsuite_mcp/py.typed
+src/gsuite_mcp/serialize.py
+src/gsuite_mcp/server.py
+src/gsuite_mcp/services.py
+src/gsuite_mcp.egg-info/PKG-INFO
+src/gsuite_mcp.egg-info/SOURCES.txt
+src/gsuite_mcp.egg-info/dependency_links.txt
+src/gsuite_mcp.egg-info/entry_points.txt
+src/gsuite_mcp.egg-info/requires.txt
+src/gsuite_mcp.egg-info/top_level.txt
+tests/test_mcp_server.py

gsuite_mcp-0.4.0/src/gsuite_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gsuite_mcp-0.4.0/src/gsuite_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gsuite-mcp = gsuite_mcp.server:main

gsuite_mcp-0.4.0/src/gsuite_mcp.egg-info/requires.txt

@@ -0,0 +1,2 @@
+gsuite-sdk>=0.3.0
+mcp<3,>=2.3

gsuite_mcp-0.4.0/src/gsuite_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+gsuite_mcp

gsuite_mcp-0.4.0/tests/test_mcp_server.py

@@ -0,0 +1,346 @@
+"""The MCP server, through an in-memory MCP client, on mocked SDK clients."""
+
+import json
+from datetime import UTC, date, datetime
+from unittest.mock import MagicMock
+
+import pytest
+from mcp.client import Client
+
+from gsuite_calendar import Event
+from gsuite_contacts import Contact
+from gsuite_core.exceptions import NotFoundError, PermissionDeniedError
+from gsuite_drive import File, Permission
+from gsuite_gmail import Message
+from gsuite_mcp import Services, build_server
+from gsuite_mcp.serialize import to_json
+from gsuite_tasks import Task
+
+DOC = "application/vnd.google-apps.document"
+SHEET = "application/vnd.google-apps.spreadsheet"
+
+
+@pytest.fixture
+def auth():
+    mock = MagicMock(name="auth")
+    mock.is_authenticated.return_value = True
+    mock.get_user_email.return_value = "me@example.com"
+    mock.credentials.scopes = ["https://www.googleapis.com/auth/gmail.modify"]
+    return mock
+
+
+@pytest.fixture
+def services(auth):
+    svc = Services(auth)
+    for name in ("gmail", "calendar", "drive", "sheets", "tasks", "contacts"):
+        svc.__dict__[name] = MagicMock(name=name)  # replaces the cached_property
+    return svc
+
+
+@pytest.fixture
+def server(services):
+    return build_server(services)
+
+
+async def call(server, tool, /, **arguments):
+    async with Client(server) as client:
+        result = await client.call_tool(tool, arguments)
+    text = result.content[0].text if result.content else ""
+    if result.is_error:
+        return "error", text
+    return "ok", json.loads(text)
+
+
+def _message(**overrides):
+    fields = {
+        "id": "m1",
+        "thread_id": "t1",
+        "subject": "Invoice",
+        "sender": "billing@example.com",
+        "recipient": "me@example.com",
+        "date": datetime(2026, 3, 1, 10, tzinfo=UTC),
+        "snippet": "Your invoice",
+        "plain": "Body text",
+        "labels": ["INBOX"],
+    }
+    fields.update(overrides)
+    return Message(**fields)
+
+
+class TestTools:
+    async def test_tools_are_annotated(self, server):
+        async with Client(server) as client:
+            tools = {t.name: t for t in (await client.list_tools()).tools}
+
+        assert len(tools) == 23
+        assert tools["gmail_search"].annotations.read_only_hint is True
+        assert tools["gmail_send"].annotations.read_only_hint is False
+        assert tools["gmail_send"].annotations.destructive_hint is False
+        assert tools["calendar_delete_event"].annotations.destructive_hint is True
+        assert tools["sheets_update"].annotations.destructive_hint is True
+        assert all(t.description for t in tools.values())
+
+    async def test_auth_status(self, server):
+        status, body = await call(server, "auth_status")
+        assert status == "ok"
+        assert body["email"] == "me@example.com"
+
+
+class TestAuthErrors:
+    async def test_no_login_explains_how_to_log_in(self, auth):
+        auth.is_authenticated.return_value = False
+        auth.needs_refresh.return_value = False
+        status, text = await call(build_server(Services(auth)), "gmail_search", query="x")
+        assert status == "error"
+        assert "gsuite auth login" in text
+
+    async def test_expired_token_is_refreshed(self, auth, services, server):
+        auth.is_authenticated.return_value = False
+        auth.needs_refresh.return_value = True
+        services.gmail.search.return_value = []
+        assert await call(server, "auth_status") == (
+            "ok",
+            {"authenticated": True, "email": "me@example.com", "scopes": auth.credentials.scopes},
+        )
+        auth.refresh.assert_called_once()
+
+    async def test_missing_scope_hint(self, services, server):
+        services.tasks.list_tasks.side_effect = PermissionDeniedError("tasks", "list")
+        status, text = await call(server, "tasks_list")
+        assert status == "error"
+        assert "--scopes default,tasks,contacts" in text
+
+    async def test_other_sdk_errors(self, services, server):
+        services.contacts.get.side_effect = NotFoundError("contacts", "contact", "c9")
+        status, text = await call(server, "contacts_get", contact_id="c9")
+        assert status == "error"
+        assert "NotFoundError" in text
+
+
+class TestGmail:
+    async def test_search_returns_summaries(self, services, server):
+        services.gmail.search.return_value = [_message()]
+
+        status, body = await call(server, "gmail_search", query="is:unread", max_results=5)
+
+        assert status == "ok"
+        assert body["count"] == 1
+        assert body["results"] == [
+            {
+                "id": "m1",
+                "thread_id": "t1",
+                "subject": "Invoice",
+                "sender": "billing@example.com",
+                "date": "2026-03-01T10:00:00+00:00",
+                "snippet": "Your invoice",
+                "labels": ["INBOX"],
+                "attachments": [],
+            }
+        ]
+        services.gmail.search.assert_called_once_with("is:unread", max_results=5)
+
+    async def test_read(self, services, server):
+        services.gmail.get_message.return_value = _message()
+        status, body = await call(server, "gmail_read", message_id="m1")
+        assert body["body"] == "Body text"
+
+    async def test_read_missing(self, services, server):
+        services.gmail.get_message.return_value = None
+        assert (await call(server, "gmail_read", message_id="x"))[0] == "error"
+
+    async def test_send_and_reply(self, services, server):
+        services.gmail.send.return_value = _message(id="s1")
+        services.gmail.get_message.return_value = _message()
+        services.gmail.reply.return_value = _message(id="r1")
+
+        assert (await call(server, "gmail_send", to=["a@b.c"], subject="Hi", body="x"))[1] == {
+            "id": "s1",
+            "thread_id": "t1",
+        }
+        assert services.gmail.send.call_args.kwargs["to"] == ["a@b.c"]
+        await call(server, "gmail_reply", message_id="m1", body="Thanks", reply_all=True)
+        services.gmail.reply.assert_called_once_with(
+            services.gmail.get_message.return_value, "Thanks", reply_all=True
+        )
+
+    async def test_draft(self, services, server):
+        services.gmail.create_draft.return_value = MagicMock(id="d1")
+        status, body = await call(server, "gmail_create_draft", to=["a@b.c"], subject="S", body="B")
+        assert body == {"draft_id": "d1"}
+
+
+class TestCalendar:
+    async def test_list(self, services, server):
+        services.calendar.get_upcoming.return_value = [
+            Event(id="e1", summary="Sync", start=datetime(2026, 3, 2, 10, tzinfo=UTC))
+        ]
+        status, body = await call(server, "calendar_list_events", days=2)
+        (event,) = body["results"]
+        assert event["summary"] == "Sync"
+        assert event["start"] == "2026-03-02T10:00:00+00:00"
+        assert "raw" not in event
+
+    async def test_create_timed_and_all_day(self, services, server):
+        services.calendar.create_event.return_value = Event(id="e1", summary="x")
+
+        await call(
+            server,
+            "calendar_create_event",
+            summary="Sync",
+            start="2026-03-02T10:00",
+            meet=True,
+            send_updates="all",
+        )
+        kwargs = services.calendar.create_event.call_args.kwargs
+        assert kwargs["start"] == datetime(2026, 3, 2, 10)
+        assert kwargs["all_day"] is False
+        assert (kwargs["meet"], kwargs["send_updates"]) == (True, "all")
+
+        await call(server, "calendar_create_event", summary="Holiday", start="2026-03-24")
+        kwargs = services.calendar.create_event.call_args.kwargs
+        assert kwargs["start"] == date(2026, 3, 24)
+        assert kwargs["all_day"] is True
+
+    async def test_bad_date(self, server):
+        status, text = await call(server, "calendar_create_event", summary="x", start="tomorrow")
+        assert status == "error"
+        assert "ISO" in text
+
+    async def test_delete_missing(self, services, server):
+        services.calendar.delete_event.return_value = False
+        assert (await call(server, "calendar_delete_event", event_id="e9"))[0] == "error"
+
+    async def test_free_busy_needs_times(self, services, server):
+        status, _ = await call(
+            server, "calendar_free_busy", time_min="2026-03-02", time_max="2026-03-03"
+        )
+        assert status == "error"
+        services.calendar.get_free_busy.return_value = {"primary": []}
+        status, body = await call(
+            server, "calendar_free_busy", time_min="2026-03-02T09:00", time_max="2026-03-02T18:00"
+        )
+        assert body == {"primary": []}
+
+
+class TestDrive:
+    async def test_search_by_name_or_query(self, services, server):
+        services.drive.search.return_value = [
+            File(id="f1", name="a.pdf", mime_type="application/pdf")
+        ]
+        status, body = await call(server, "drive_search", name="a")
+        assert body["results"][0]["id"] == "f1"
+        services.drive.list_files.return_value = []
+        await call(server, "drive_search", query="trashed = false", max_results=5)
+        services.drive.list_files.assert_called_once_with(query="trashed = false", max_results=5)
+
+    @pytest.mark.parametrize(
+        ("mime", "export"),
+        [(DOC, "txt"), (SHEET, "csv"), ("application/vnd.google-apps.presentation", "txt")],
+    )
+    async def test_read_google_files_as_text(self, services, server, mime, export):
+        services.drive.get.return_value = File(id="f1", name="Doc", mime_type=mime)
+        services.drive.export.return_value = b"hello"
+        status, body = await call(server, "drive_read_file", file_id="f1")
+        assert body["text"] == "hello"
+        services.drive.export.assert_called_once_with("f1", export)
+
+    async def test_read_text_file_and_truncate(self, services, server):
+        services.drive.get.return_value = File(id="f1", name="a.txt", mime_type="text/plain")
+        services.drive.get_content.return_value = b"0123456789"
+        status, body = await call(server, "drive_read_file", file_id="f1", max_chars=4)
+        assert (body["text"], body["truncated"]) == ("0123", True)
+
+    async def test_binary_refused(self, services, server):
+        services.drive.get.return_value = File(id="f1", name="a.pdf", mime_type="application/pdf")
+        status, text = await call(server, "drive_read_file", file_id="f1")
+        assert status == "error"
+        assert "gsuite drive download f1" in text
+
+    async def test_share(self, services, server):
+        assert (await call(server, "drive_share", file_id="f1"))[0] == "error"
+        services.drive.add_permission.return_value = Permission(
+            id="p1", type="anyone", role="reader"
+        )
+        status, body = await call(server, "drive_share", file_id="f1", anyone=True)
+        assert body["type"] == "anyone"
+        assert services.drive.add_permission.call_args.kwargs["type"] == "anyone"
+
+
+class TestSheets:
+    @pytest.mark.parametrize(
+        ("spreadsheet", "method"),
+        [
+            ("https://docs.google.com/spreadsheets/d/abc/edit", "open_by_url"),
+            ("1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789", "open_by_key"),
+            ("Budget", "open"),
+        ],
+    )
+    async def test_resolves_url_id_or_title(self, services, server, spreadsheet, method):
+        ws = getattr(services.sheets, method).return_value.sheet1
+        ws.title = "Data"
+        ws.get.return_value = [["a", "b"]]
+
+        status, body = await call(server, "sheets_read", spreadsheet=spreadsheet, range="A1:B1")
+
+        assert body == {"sheet": "Data", "range": "A1:B1", "values": [["a", "b"]]}
+
+    async def test_missing_tab(self, services, server):
+        services.sheets.open.return_value.worksheet.return_value = None
+        status, text = await call(server, "sheets_read", spreadsheet="Budget", sheet="Nope")
+        assert status == "error"
+
+    async def test_title_not_found(self, services, server):
+        services.sheets.open.side_effect = ValueError("Spreadsheet not found: Budget")
+        status, text = await call(server, "sheets_read", spreadsheet="Budget")
+        assert (status, text.endswith("Spreadsheet not found: Budget")) == ("error", True)
+
+    async def test_writes(self, services, server):
+        ws = services.sheets.open.return_value.sheet1
+        ws.title = "Data"
+        ws.upsert.return_value = {"updated": 1, "appended": 0}
+
+        assert (await call(server, "sheets_append", spreadsheet="B", rows=[["x", 1]]))[1][
+            "appended"
+        ] == 1
+        ws.append_rows.assert_called_once_with([["x", 1]])
+        await call(server, "sheets_update", spreadsheet="B", range="B2", values=[[5]])
+        ws.update.assert_called_once_with("B2", [[5]])
+        status, body = await call(
+            server, "sheets_upsert", spreadsheet="B", rows=[{"name": "Ana"}], key="name"
+        )
+        assert body == {"updated": 1, "appended": 0}
+
+
+class TestTasksAndContacts:
+    async def test_tasks(self, services, server):
+        services.tasks.list_tasks.return_value = [
+            Task(id="t1", title="Pay", tasklist_id="@default", due=date(2026, 3, 1))
+        ]
+        status, body = await call(server, "tasks_list", due_before="2026-03-31")
+        assert body["results"][0]["due"] == "2026-03-01"
+        assert services.tasks.list_tasks.call_args.kwargs["due_max"] == date(2026, 3, 31)
+
+        services.tasks.create_task.return_value = Task(id="t2", title="New", tasklist_id="@default")
+        await call(server, "tasks_add", title="New", due="2026-04-01T09:00")
+        assert services.tasks.create_task.call_args.kwargs["due"] == date(2026, 4, 1)
+
+        services.tasks.complete_task.return_value = Task(
+            id="t2", title="New", tasklist_id="@default", status="completed"
+        )
+        assert (await call(server, "tasks_complete", task_id="t2"))[1]["status"] == "completed"
+
+    async def test_contacts(self, services, server):
+        services.contacts.search.return_value = [
+            Contact(resource_name="people/c1", display_name="Ana", emails=["a@x.com"])
+        ]
+        status, body = await call(server, "contacts_search", query="ana")
+        assert body["results"][0]["emails"] == ["a@x.com"]
+        services.contacts.get.return_value = None
+        assert (await call(server, "contacts_get", contact_id="c9"))[0] == "error"
+
+
+def test_to_json_skips_raw_and_private_fields():
+    message = _message()
+    data = to_json(message)
+    assert "raw" not in data and "_gmail" not in data and "plain" not in data
+    assert data["date"] == "2026-03-01T10:00:00+00:00"