mise-en-space

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.

Why another tool for LLMs to use Google Workspace?

Google's official Workspace MCP !Stars 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 !Stars 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 !Stars 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 !Stars — pre-built Gmail filter templates. Good ergonomics for a single source, but again, just a single source.
• aaronsb/google-workspace-mcp !Stars — 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 !Stars — 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. PDFs use hybrid extraction (markitdown → Drive OCR fallback). 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

| Verb | Purpose | Deposits files? | |------|---------|-----------------| | search | Find files and emails across Drive and Gmail (plus activity and calendar) | Yes — results JSON | | fetch | Extract content to .mise/ as markdown/CSV | Yes — content folder | | do | Act on Workspace — 18 operations: create, copy, move, rename, share, overwrite, prepend, append, replace_text, draft, reply_draft, archive, star, label, comment, comment_reply, trash, setup_oauth | Varies |

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

<!-- GENERATED:SKILLS:START --> 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 .

| Skill | What it does | |-------|--------------| | /mise | Orchestrates content fetching via the mise MCP server's search/fetch/do tools | <!-- GENERATED:SKILLS:END -->

Supported Content Types

| What's in the larder | What the chef gets | |--------|-------------| | Google Docs | Markdown + open comments | | Google Sheets | CSV + chart PNGs + open comments | | Google Slides | Markdown + selective thumbnails + open comments | | Gmail threads | Markdown with signature stripping via talon, attachment extraction | | PDFs | Markdown (markitdown → Drive OCR fallback) | | Office files (DOCX/XLSX/PPTX) | Markdown or CSV via Drive conversion | | Video/Audio | AI summary + metadata (requires a chrome-debug browser session) | | Images | Deposited as-is; SVG rendered to PNG |

Architecture

server.py       MCP server (thin wrappers around tools; ≤500 lines, enforced)
cli.py          CLI interface (same tools, no MCP)
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.

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/

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), Contacts (read), Docs/Sheets/Slides (read+write), Drive Activity, Drive Labels, Calendar. See oauth_config.py for the full list and rationale.

<details> <summary>Bringing your own GCP project (advanced)</summary>

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

1. Configure OAuth consent screen (External, add your email as test user)
2. Create OAuth credentials (Web Application type)

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

1. Download the JSON and replace credentials.json in the repo root
2. Run uv run python -m auth

</details>

Troubleshooting:

| Problem | Fix | |---------|-----| | redirect_uri_mismatch | Only applies if using your own GCP project — add http://localhost:3000/oauth/callback to redirect URIs | | access_denied | Add your email as a test user on the OAuth consent screen | | No browser available | Use --manual flag, or SSH with port forwarding (-L 3000:localhost:3000) |

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.

| Operation | Typical | Range | Notes | |-----------|---------|-------|-------| | Search (single source) | ~1s | 0.2–1.3s | Drive and Gmail similar | | Search (Drive + Gmail) | ~0.8s | 0.6–1.1s | Parallel — faster than either alone | | Fetch: Google Doc | ~2s | 1.7–3.1s | Single API call | | Fetch: Gmail thread | ~2.4s | 1.8–3.0s | Thread + message batch | | Fetch: PDF | ~2.5s | 2.1–3.0s | markitdown; complex PDFs fall back to Drive OCR (5–15s) | | Fetch: Google Sheet | ~4s | 1.9–5.9s | 2 API calls (metadata + values) | | Fetch: Slides (7 slides) | ~6s | 3.1–9.3s | ~0.5s per thumbnail, sequential | | Fetch: XLSX | ~6s | 6.1–6.7s | Drive upload → convert → export | | Fetch: DOCX | ~9s | 8.3–9.9s | Same pipeline, larger payloads |

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.