Workspace Operator (formerly yet-another-google-mcp) runs on your machine, talks to Google over your own OAuth client, and gives an AI agent the operations that turn "read my inbox" into "do the work and let me undo it": staged Apps Script updates, file transfer in both directions, presentation assembly, sheet formatting, threaded replies and attachments.

67 tools · 3 resources · 3 resource templates · 8 prompts, every tool annotated with readOnlyHint / destructiveHint.

Nothing here is tied to a specific account, spreadsheet or document: every tool takes identifiers and ranges, and all examples use synthetic data.

How it compares

Official servers are the right default for "ask my mail a question". Workspace Operator is for "change the workspace and be able to roll it back".

What you get

Plus 3 resources, 3 resource templates and 8 prompts — see the tool catalog.

Quick start

1 — Install

pip install workspace-operator-mcp

From source (development):

git clone https://github.com/Artoxem/workspace-operator.git
cd workspace-operator
python -m venv .venv && .venv\Scripts\activate    # Windows
pip install -r requirements.txt

Python 3.10 or newer. The package installs the workspace-operator command; the python -m workspace_operator form works from a source checkout too.

2 — Google OAuth

1. Create an OAuth 2.0 Client ID (type: Desktop app) in Google Cloud Console.
2. Enable these APIs: Drive, Docs, Sheets, Slides, Gmail, Calendar, Apps Script.
3. Download the client JSON — the server will read it on first run.

Step by step: docs/AUTH_SETUP.md · docs/ru/AUTH_SETUP.md Upgrading? Slides needs the .../auth/presentations scope — re-run the OAuth flow once.

3 — Configure

cp config.example.yaml config.yaml

client_secrets_file: "C:\\Users\\you\\.google\\oauth.keys.json"
token_file: "C:\\Users\\you\\.google\\token.json"
backup_dir: "C:\\Users\\you\\.google\\backups"
mcp_auth_token: "MySecretToken_2026!"
tool_profile: "read-write"      # full | read-write | read-only

mcp_auth_token is a local activation key, not network security: the server refuses to handle tools until it is set. Every key can be overridden by an environment variable — see docs/SECURITY.md.

4 — Connect a client

{
  "mcpServers": {
    "workspace-operator": {
      "command": "python",
      "args": ["D:\\DEV\\workspace-operator\\server.py"],
      "env": {
        "MCP_CONFIG_FILE": "D:\\DEV\\workspace-operator\\config.yaml",
        "MCP_AUTH_TOKEN": "MySecretToken_2026!",
        "MCP_TOOL_PROFILE": "read-write"
      },
      "timeoutSeconds": 300,
      "tools": { "workspace_search": { "eager": true } }
    }
  }
}

{
  "mcpServers": {
    "workspace-operator": {
      "command": "python",
      "args": ["D:\\DEV\\workspace-operator\\server.py"],
      "env": {
        "MCP_CONFIG_FILE": "D:\\DEV\\workspace-operator\\config.yaml",
        "MCP_AUTH_TOKEN": "MySecretToken_2026!"
      }
    }
  }
}

Tool profiles

A profile is a server-side allow-list: tools outside it are neither listed nor callable. It complements OAuth scopes (what Google allows) and client permissions (what the agent may do without asking).

tool_profile: "read-write"
# Optional, applied on top. Deny wins over allow.
allowed_tools: ["workspace_search", "find_files", "read_sheet", "read_email"]
denied_tools: ["send_email", "share_file"]

Environment overrides: MCP_TOOL_PROFILE, MCP_ALLOWED_TOOLS, MCP_DENIED_TOOLS. A blocked call returns a clear explanation instead of failing silently.

Operations

python -m workspace_operator doctor     # config, token, scopes, API reachability
python -m workspace_operator tools      # catalog (--profile read-only, --json)
python -m workspace_operator serve      # stdio server (same as python server.py)

In dry-run the read-only tools still work, so an agent can explore data while every write is turned into an explicit preview.

HTTP transport (localhost first)

python -m workspace_operator serve --http --port 8765

• binds 127.0.0.1 by default — not reachable from the network;
• every request needs Authorization: Bearer <mcp_auth_token>; extra per-client tokens can be listed under http_tokens in config.yaml, and the audit log records the token name as client;
• DNS-rebinding protection is on: only expected Host headers pass, browser origins are denied unless explicitly allowed;
• GET /healthz is unauthenticated and returns only version and transport info;
• binding a non-loopback address requires both --allow-network and --insecure; loopback names accept any host port (containers, proxies), anything else needs an explicit --allow-host; --insecure, so network exposure is always deliberate.

Docker

docker pull ghcr.io/artoxem/workspace-operator:latest

docker run --rm -p 127.0.0.1:8765:8765 \
  -v "$HOME/.google:/home/app/.google" \
  -v "$PWD/config.docker.yaml:/app/config.yaml:ro" \
  -e MCP_AUTH_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')" \
  ghcr.io/artoxem/workspace-operator:latest

The image runs as an unprivileged user (uid 10001), publishes only to loopback and mounts the Google credentials read-write, because the server refreshes the token in place. docker compose up --build builds the same image locally.

Tool catalog

Resources

Prompts

Safety by default

⚠️ An agent can reach everything your OAuth token can. Use read-only scopes and the read-only profile for sensitive accounts — docs/SECURITY.md.

How it works

server.py                    MCP server: 67 tool definitions, resources, prompts, profiles
workspace_operator/
├─ profiles.py               read-only / read-write / full + allow-deny lists
├─ config.py                 config file + environment overrides
├─ auth.py                   OAuth 2.0 credentials and token cache
├─ text.py                   entity/whitespace normalisation, timestamps, error hints
├─ operations.py             staged-operation store for Apps Script
├─ security.py               token and email checks
├─ runtime.py                retries, audit log, dry-run helpers
├─ cli.py                    doctor / tools / serve
└─ handlers/
   ├─ search.py              workspace_search — Drive + Gmail + Calendar
   ├─ files.py               drive_upload / drive_download / drive_export
   ├─ formatting.py          sheet_format request builders
   ├─ gmail_threads.py       threads, attachments, in-thread replies
   ├─ slides.py              presentations
   ├─ calendar_writes.py     update / delete / invite responses
   ├─ report.py              report_from_sheet: stats + document
   ├─ digest.py              digest across mail, calendar and drive
   ├─ compare.py             table diff by key column
   ├─ template.py            clone a file and fill placeholders
   ├─ deck.py                table → presentation
   ├─ drive.py  sheets.py  docs.py
   ├─ gmail.py  calendar.py  apps_script.py
tests/                       unit, live and round-trip checks
antigravity/                 ready-to-paste mcp_config.json
skills/google-workspace/     Agent Skill: when to use which tool

Design rules:

• every handler returns a string — exceptions never reach the transport;
• writes are staged, confirmed or drafted, never silent;
• Apps Script is a two-phase commit with an automatic backup;
• server-side profiles keep the exposed surface small.

Testing

python -m unittest discover -s tests -v     # 247 unit tests, no network
python tests/live_smoke.py                  # 51 checks against a real account
python tests/pptx_roundtrip.py deck.pptx    # 5 checks: pptx → Slides → replace

The live suite is self-cleaning: it uploads and trashes a temp file, creates and trashes a presentation and a spreadsheet, drafts and deletes a reply, downloads an attachment and removes it. tests/test_docs.py keeps this README, the docs and the code in sync (tool counts, profile numbers, links, examples).

Documentation

🇬🇧 English

🇷🇺 На русском

Roadmap

• Cross-product search, tool profiles
• Files, Slides, Apps Script execution
• Sheet formatting
• Gmail threads, attachments, replies
• Calendar update/delete/respond
• Composite tools: report_from_sheet, digest, compare_tables, clone_and_fill
• Optional HTTP transport (Streamable HTTP, stateless, localhost-first)

Responsibility

You are responsible for what the agent does with your account. Read docs/SECURITY.md, start with read-only, keep backups on.