mise-en-space

Status

Robustness: Stable — in daily use, regular releases (currently v0.7.4) Works with: Claude Code, Amp, Gemini CLI (any MCP client) Install: Configure as MCP server (see below) Requires: Python 3.11+, Google OAuth credentials

An MCP sous-chef for Google Workspace that provides a mise en place for knowledge work. Peel and pith removed, everything prepped and in its place, ready for Claude to cook with.

Related MCP server: google-cli-mcp

Why another tool for LLMs to use Google Workspace?

Google's official Workspace MCP has 50 tools and requires multiple round-trips for basic tasks — search Gmail, get back a list of IDs, call again for each message, all of it burning context. Because it's essentially a thin wrapper over the Workspace APIs, the tool definitions alone take up ~15k of tokens every session.

Looking around for others, I found plenty of inspiration, but also some snags:

• taylorwilsdon/google_workspace_mcp covers every Google service, but returns all content inline — a 70-slide deck or 30-message thread lands straight in your context window

• felores/gdrive-mcp-server deposits files to disk (Docs→Markdown, Sheets→CSV) the way I wanted, and also used a clever trick to get Drive to do high quality conversions, but only does Google Drive, so its coverage was limited for my needs

• GongRzhe/Gmail-MCP-Server — pre-built Gmail filter templates. Good ergonomics for a single source, but again, just a single source.

• aaronsb/google-workspace-mcp — deposits files to disk with per-account folders. The right idea for file handling IMO - don't spam the caller's context window, but I didn't need multi-account support

• a-bonus/google-docs-mcp — tab-aware Docs extraction. Everyone else ignores multi-tab documents.

I wanted something that had the best of all these ideas:

• Sous-chef philosophy. Fetch a doc and get the comments too. Fetch an email and get the attachments extracted. Don't make the chef ask for every ingredient separately.

• Clean extraction. PDF text comes from poppler's pdftotext -layout — measured best on a 636-probe census of real corporate PDFs (97.4% verbatim value survival, 100% on big-table pages) — with Drive server-side OCR as the fallback for scans. Office files convert automatically.

• Opinionated, LLM-first control surface 3 tools not 50 - search, fetch, do. ~3k tokens of tool definitions and everything routes through the same three verbs.

• One call, rich results. Gmail search returns subjects, senders, snippets, and attachment names — not a bag of IDs requiring N+1 follow-ups.

• Filesystem-deposits. Content goes to disk as markdown/CSV, not into the context window. Claude reads (and greps) what it needs.

• Companion Skill. I like the pattern where we provide a tool and a companion Skill that acts as the instruction manual on how to use it.

• MCP Optional. Option for CLI based interactions e.g. if you want to use a different agent harness like pi.

The 3 Verbs

CLI

For agents without MCP support — search and fetch in full, plus create (the most common do operation):

mise search "quarterly reports"
mise search "from:alice budget" --sources gmail
mise fetch 1abc123def456
mise create "Title" --content "# Markdown content"

Skills

1 skill, tabled from skills/*/SKILL.md frontmatter by render-skills.py — regenerate from this repo's root with uv run --script ../batterie-de-savoir/scripts/render-skills.py .

Supported Content Types

Architecture

server.py       MCP server (thin wrappers around tools; ≤500 lines, enforced)
cli.py          CLI interface (same tools, no MCP)
mise_en_space/  Library facade — import mise for in-process use (see below)
tools/          Business logic — routing, orchestration, do() dispatch, remote mode
adapters/       Thin Google API wrappers (one per service)
extractors/     Pure functions — no I/O, no MCP awareness (testable without APIs)
workspace/      File deposit management
resources/      MCP resource text (mise://docs/*)
skills/         Claude skill (auto-discovered by plugin system)

Layer rules:

• Extractors never import from adapters or tools (no I/O)

• Tools wire adapters → extractors → workspace

• Server and CLI are both thin wrappers around tools

• All of it mechanically enforced by tests/unit/test_architecture.py — including the root-level utility files, by discovery

Adding a new content type means: adapter (API call), extractor (parse), tool (wire + deposit). The layers are independent.

Using mise as a library

Services that run headless (glaneur's nightly harvest, Garni's Cloud Run agents) import mise in-process instead of speaking MCP. The contract is the mise_en_space package — one class, the same three verbs:

from mise_en_space import Mise

ws = Mise(ambient=True, base_path=workdir)   # Cloud Run SA via ADC; also:
                                             # token_path=..., credentials=..., or Mise()
listing = ws.search(folder_id=CORPUS)        # discovery
result = ws.fetch(file_id)                   # deposit: manifest.json + content.md
doc = ws.do("create", title=..., content=markdown, folder_id=SHARED_DRIVE_FOLDER)

The worked example — hydrate a Drive folder, write a Doc back, as a service account — is examples/hydrate_and_write_back.py; its header covers installing the wheel (you supply jeton yourself — uv source maps don't ride wheel metadata) and the service-account facts that bite (writes land only in Shared Drives). The full credential and deposit contract is the package docstring: python -c "import mise_en_space; help(mise_en_space)".

Three facts a headless PDF pipeline needs. The bulk-text tool is poppler's pdftotext -layout — the extraction primary since suite 1.67 — and the wheel cannot bundle it: put poppler-utils in the consumer image (Dockerfile apt-get install poppler-utils) or PDF text silently degrades to markitdown (worse on tables) or Drive conversion (slow, needs write scope), with only a cue warning to say so. fetch(file_id, thumbnails=False) skips page/slide PNG rendering — measured 154s → 59s and 77 MB → 0 of deposit weight on a 256-page annual report — so pass it whenever nothing will look at pixels. And no extraction path guarantees page boundaries: form-feed survival is per-PDF (markitdown kept a two-page fixture's marker and dropped all 255 of that same annual report's), so a page-citing consumer must gate on the measured fields every PDF deposit carries — page_markers (form feeds in content.md) against pdf_pages (poppler's count, when available) — and heed the warning cue that fires whenever per-page citations can't be derived. Never infer page fidelity from extraction_method.

Setup

1. Clone and install

git clone https://github.com/spm1001/mise-en-space.git
cd mise-en-space
uv sync    # requires uv — https://docs.astral.sh/uv/

System prerequisite: poppler. PDF text extraction (pdftotext -layout) and PDF/deck page thumbnails shell out to poppler:

sudo apt-get install poppler-utils   # Debian/Ubuntu
brew install poppler                 # macOS

Without it mise still works — PDF text falls back to markitdown (measurably worse on tables) or Drive conversion, and thumbnails are skipped — and both the session-start hook and every affected fetch say so rather than degrading silently.

2. Google OAuth

mise-en-space uses jeton for OAuth.

Quick version: credentials.json ships with the repo. Just run uv run python -m auth --auto.

uv run python -m auth --auto             # Opens browser + localhost listener (machine with a browser)
uv run python -m auth                    # Headless — prints the consent URL to paste into any browser
uv run python -m auth --code URL_OR_CODE # Exchange the code from the headless flow

With --auto, grant permissions in the browser and you're done.

Scopes requested: Drive (read+write), Gmail (read+write), Docs/Sheets/Slides (read+write), Drive Activity, Drive Labels, Calendar, Forms, and the staff directory (read). The directory scope is admin.directory.user.readonly, which reads more alarming than it is — mise only ever calls the Directory API's domain_public view, documented by Google as available to any user on the domain, and never the administrator view. See oauth_config.py for the full list and rationale.

If you prefer your own OAuth credentials instead of the bundled ones:

1. Create or select a Google Cloud project

2. Enable these APIs in APIs & Services > Library:

   • Google Drive API, Gmail API, Google Docs API, Google Sheets API

   • Google Slides API, Google Calendar API, Drive Activity API, Drive Labels API

3. Configure OAuth consent screen (External, add your email as test user)

4. Create OAuth credentials (Web Application type)

   • Add http://localhost:3000/oauth/callback as an authorized redirect URI

5. Download the JSON and replace credentials.json in the repo root

6. Run uv run python -m auth

Troubleshooting:

3. Add to Claude as MCP server

Add to ~/.claude.json:

{
  "mcpServers": {
    "mise": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/path/to/mise-en-space", "run", "python", "server.py"]
    }
  }
}

4. Link the skill (recommended)

The skills/ directory contains a Claude skill that teaches Claude how to use mise effectively — Gmail operators, the exploration loop, comment checking patterns. The plugin system auto-discovers skills from skills/*/SKILL.md.

# For pi
ln -s /path/to/mise-en-space/skills/mise ~/.pi/agent/skills/mise

Without the skill, Claude can call the tools but won't know the patterns that make them useful (like following email_context hints or filtering large results with jq).

5. Email attachment extractor (optional)

The apps-script/ directory contains a Google Apps Script that runs in your Google account, extracting email attachments to dated Drive folders (Email Attachments/YYYY-MM/). This enables Drive fullText search to find content inside PDF attachments — the "pre-exfil detection" pattern that makes mise searches across Gmail and Drive seamless.

See apps-script/README.md for setup instructions.

What to Expect (Latency)

MCP server startup is ~1.3s (import + first auth). After that, the server stays alive — subsequent calls skip startup.

Benchmarked 9 Feb 2026 at fd5f9d0, 3 runs each, warm server, London → Google APIs.

The slow paths: Office files (DOCX/XLSX) are unavoidably slow — Drive does server-side conversion (upload → convert → export → cleanup). Gmail attachments that are Office files are listed but not auto-extracted for this reason; use fetch(thread_id, attachment="file.xlsx") on demand.

Detailed timing data and flow diagrams: docs/information-flow.md

The Kitchen

Mise en Space is part of Batterie de Savoir — a suite of tools for AI-assisted knowledge work. See the full brigade and design principles for how the tools fit together.