google-slides-mcp

A uvx-runnable MCP server for low-level interaction with the Google Slides API.

It is built to be more capable than typical Slides MCPs. In addition to reading presentations and slides as structured objects, it can:

• Find existing presentations in your Drive — native Google Slides and PowerPoint (.pptx) files — by name, content, or recency ("the last deck I created"), and import a .pptx as a native Slides deck so every other tool works on it.

• Reuse a "model template" / showcase deck with full fidelity. Copy a styled showcase deck, duplicate the example slides you want (e.g. a 3‑column layout), fill them with content, and prune the rest — leaving a result functionally identical to hand‑editing the showcase (masters, layouts, theme and colors are all preserved).

• Edit element bounding boxes in points (position/size) without doing affine matrix math, plus raw transform / z‑order / grouping control.

• Render slides to PNG and diff two renders so you can verify output is pixel‑perfect.

• Work with review comments. See exactly where every comment thread sits — a slide, an element, a range of text, table cells or the speaker notes — reply to and resolve them, and leave anchored comments to propose a change without editing (Slides has no suggestion mode). Text edits through set_element_text change only the words that differ, so comments on the rest stay attached.

• Issue raw batchUpdate requests for anything the convenience tools don't cover, optionally guarded by the revision you read.

Every tool makes a bounded number of API calls and returns trimmed output, so an LLM driving it has a predictable, finite cost.

Why the template workflow works this way

The Google Slides API has no native cross‑presentation slide copy. duplicateObject only works within one presentation, and recreating a slide's elements by hand in another deck loses fidelity (placeholder inheritance, master styling and theme colors are dropped).

The high‑fidelity pattern this server implements is:

1. copy_presentation → Drive files.copy clones the entire showcase deck, preserving masters, layouts, theme and color scheme.

2. catalog_slides → summarize the example slides so you can pick one per section.

3. duplicate_slide → copy a chosen example slide within the new deck (full fidelity).

4. replace_all_text / set_element_box → fill content and adjust layout.

5. delete_objects → prune the original showcase example slides.

6. render_page / diff_pages → verify the result.

Related MCP server: google-slides-mcp

1. Google Cloud Console setup (one time)

1. Go to the Google Cloud Console and create a project (or select an existing one).

2. Enable the APIs: APIs & Services → Library → enable both Google Slides API and Google Drive API.

3. Configure the OAuth consent screen: APIs & Services → OAuth consent screen.

   • User type: External (or Internal if you're in a Workspace org).

   • Fill in app name / support email.

   • Add the scopes .../auth/presentations and .../auth/drive.

   • Under Test users, add the Google account you'll authorize with.

   • ⚠️ While the app is in Testing status, refresh tokens expire after 7 days. Re-run the auth command when that happens, or publish the app.

4. Create credentials: APIs & Services → Credentials → Create credentials → OAuth client ID.

   • Application type: Desktop app.

   • Download the JSON — this is your client_secret.json.

Scope note: this server requests the broad auth/drive scope so it can files.copy any template you own by ID. If you only ever copy decks the app itself created, you can narrow this via GOOGLE_SLIDES_SCOPES (see below), but the showcase workflow on existing decks needs auth/drive. Google requires the fully‑qualified scope URLs (e.g. https://www.googleapis.com/auth/drive); the short names presentations / drive are accepted and expanded for you.

2. Install & first‑time login

Auth uses a standard interactive OAuth 2.0 installed‑app flow built to roll out to a team: you distribute one Desktop OAuth client JSON, and each person logs in once in a browser to cache their own personal refresh token. There is no shared, single‑user token.

You can authorize either way:

Option A — let the server do it (zero extra commands). Just configure the MCP server (next section) with your client secret. The first launch opens a browser for consent automatically and caches the token; every launch after that is silent.

Option B — log in explicitly up front (recommended for headless/server hosts, or to authorize before wiring up your MCP client):

GOOGLE_CLIENT_SECRET=/absolute/path/to/client_secret.json \
  uvx --from git+https://github.com/justparent/google-slides-mcp google-slides-mcp-auth

Either way the token is written to ~/.config/google-slides-mcp/token.json (override with GOOGLE_TOKEN_PATH / TOKEN_PATH). Once published to PyPI you'll be able to drop --from … and just run uvx google-slides-mcp-auth.

If you're deploying somewhere without a browser, set GOOGLE_SLIDES_NO_BROWSER_AUTH=1 so the server never tries to open one, and use Option B to authorize ahead of time.

3. Configure your MCP client

Add the server to Claude Desktop / Claude Code (mcpServers config):

{
  "mcpServers": {
    "google-slides": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/justparent/google-slides-mcp",
        "google-slides-mcp"
      ],
      "env": {
        "GOOGLE_CLIENT_SECRET": "/absolute/path/to/client_secret.json",
        "GOOGLE_TOKEN_PATH": "~/.config/google-slides-mcp/token.json"
      }
    }
  }
}

After PyPI publication: "args": ["google-slides-mcp"].

Environment variables

The GOOGLE_* names and the shorter aliases (CREDENTIALS_PATH / TOKEN_PATH) are interchangeable; if both are set, the GOOGLE_* name wins.

Tools

Find / import (Drive discovery)

The Slides API has no listing endpoint, so discovery goes through Drive. search_presentations covers native decks and PowerPoint files; results flag directlyEditable so you know when an import_presentation conversion is needed first. Recipes: last deck I created → order_by="createdTime desc", owned_by_me=true, max_results=1; find the corporate template → name_contains="corporate template".

Core read

Raw write

Element / transform / bounding box

Text

Review comments

Template / showcase reuse

Iteration / palette

Rendering / verification

render_page/diff_pages use the thumbnail endpoint, an expensive quota operation (300/min per project, 60/min per user). Rendering is per‑page by design — there is no whole‑deck render.

Example: build a deck from a showcase template

copy_presentation(source_id="<showcase_id>", title="Q3 Review")      → new deck id
catalog_slides(presentation_id="<new_id>")                           → pick example slides
duplicate_slide(presentation_id="<new_id>", page_id="<3col_example>", insertion_index=1)
replace_all_text(presentation_id="<new_id>", mappings={"{{title}}": "Results"})
delete_objects(presentation_id="<new_id>", object_ids=["<original_examples>..."])
render_page(presentation_id="<new_id>", page_id="<new_slide>")       → verify visually
diff_pages(presentation_id="<new_id>", page_a="<new_slide>", page_b="<showcase_example>")

Example: port your latest deck into the corporate template

search_presentations(order_by="createdTime desc", owned_by_me=true, max_results=1)
                                                                      → the source deck (or .pptx)
import_presentation(file_id="<source_id>")                            → only if the source is a .pptx
search_presentations(name_contains="corporate template", file_type="google_slides")
                                                                      → the template deck
copy_presentation(source_id="<template_id>", title="Q3 Review (rebranded)")
catalog_slides(presentation_id="<source_id>")                         → read the source content
catalog_slides(presentation_id="<new_id>")                            → pick matching template layouts
duplicate_slide / set_element_text / replace_all_text                 → rebuild each slide on-brand
render_page(presentation_id="<new_id>", page_id="<slide>")            → verify

Iterative / palette workflow

You do not have to assemble the deck in one shot. Every tool is an independent call, so you can keep adding slides across many turns ("great, now add another three‑column slide that says xyz").

The key idea is a palette: because the Slides API can only duplicate slides within one deck, keep the showcase example slides present in the working deck as reusable sources, and duplicate from them on demand. park_slides hides them (skips them in present mode) so they don't clutter the in‑progress deck, and prune_parked_slides removes them all at the very end.

# Once, at the start of a project:
copy_presentation(source_id="<showcase_id>", title="Q3 Review")   → working deck (palette embedded)
park_slides(presentation_id="<new_id>", slide_ids=[<all example ids>])   → hide the palette

# Repeat any number of times, across separate turns:
catalog_slides(presentation_id="<new_id>")                        → find the 3‑column example id (isSkipped=true)
duplicate_slide(presentation_id="<new_id>", page_id="<3col_example>")    → new live slide
set_element_text(presentation_id="<new_id>", element_id="<col1>", text="xyz")
# ...or replace_all_text(..., page_ids=["<new_slide>"]) if the example uses {{tokens}}
render_page(presentation_id="<new_id>", page_id="<new_slide>")    → verify

# Once, at the end (the skill's responsibility):
prune_parked_slides(presentation_id="<new_id>")                   → delete the palette

Why park instead of delete? park_slides keeps every layout available as a clone source for later turns. If you delete_objects an example early, a layout you never instantiated is gone from the deck (there is no cross‑deck copy).

Fallback: recreating a layout

If a needed layout was already pruned, you can rebuild a slide from the deck's layouts (visible via get_presentation(..., include_masters=True)) using createSlide with a slideLayoutReference, plus createShape/createImage via batch_update. This reproduces a layout's placeholders faithfully, but recreating an arbitrary slide's elements this way is not guaranteed pixel‑perfect — theme colors, master styling and placeholder inheritance can be lost. Prefer keeping the palette parked.

Review comments

Reviewers leave comments on slides; these tools let an assistant read them in place, act on them and answer. Slides has no suggestion mode, so a comment is also how an assistant proposes or flags a change without editing the slide.

get_presentation(presentation_id="<deck>")
  → comments: {open: 3, resolved: 1, orphaned: 0}, and openComments on each slide
list_comments(presentation_id="<deck>")
  → every open thread: content, replies, the quote it was made on, and where it sits
set_element_text / replace_all_text / batch_update       → make the change it asks for
reply_to_comment(presentation_id="<deck>", comment_id="<id>",
                 content="Changed to 14%.", action="resolve")

add_comment(presentation_id="<deck>", content="Source for this number?", text="14%")
  → flag something without touching the slide

Where a comment sits. Each location in list_comments has a kind: slide, element (a whole shape, image or table), text (a range in a shape, with the words it covers), table_cells (cells, each with its range) or notes (speaker notes), plus slideId and slideIndex. add_comment takes the same:

Worth knowing

• Reading comments needs comment access to the deck. The overviews (get_presentation, get_page, list_slides) use Google's "current access" mode, which (per its documentation) leaves comments out rather than failing for a view-only user; list_comments reports the error instead.

• A thread whose commented content was deleted stays open but has no location: it is flagged orphaned and keeps its quote. set_element_text and replace_all_text keep comments attached to the words they leave in place, and to a phrase that is replaced; deleting a shape, or deleting and retyping text through raw requests, detaches them.

• Every comment write bumps the deck's revisionId. To guard an index-based edit, pass the revisionId you last saw as required_revision_id to batch_update; every write returns the new one.

• duplicate_slide puts a text-range thread on the copy as well (one thread, two locations). Drive files.copy (copy_presentation) does not copy comments.

• Assignees and @mentions are not exposed because they notify people; batch_update accepts insertComment with assigneeEmailAddress if you need one.

• Needs google-api-python-client 2.201.0 or newer (older releases don't know the comments parameters). No new OAuth scope is needed.

Development

uv venv && uv pip install -e ".[dev]"
uv run pytest                 # unit + smoke tests (no network/credentials)
uv build                      # build sdist + wheel

A ready-to-use Claude skill describing the canonical workflow lives at example_skill/SKILL.md.

The codebase is intentionally small and modular so it can back that skill:

Troubleshooting

• "No cached Google credentials …" — run google-slides-mcp-auth first.

• Token stopped working after ~7 days — your OAuth app is in Testing status; re-run the auth command or publish the consent screen.

• insufficient scopes / can't copy a template — ensure the auth/drive scope is granted (re-run auth after enabling it on the consent screen).

• unexpected keyword argument 'commentsViewMode' — google-api-python-client is older than 2.201.0; upgrade it.

• No module named 'mcp.server.fastmcp' — mcp 2.x was installed, which renamed that module. This server needs mcp<2 (the package metadata now says so).

• "Access blocked: Authorization Error" / Error 400: invalid_scope (Some requested scopes were invalid) — the scopes sent weren't fully‑qualified URLs. Use the full https://www.googleapis.com/auth/... form (or the short names presentations / drive, which are now expanded for you) in GOOGLE_SLIDES_SCOPES.

License

MIT — see LICENSE.