gslides-api MCP Server

The gslides-api MCP (Model Context Protocol) server exposes Google Slides operations as tools for AI assistants. This enables AI systems to read, modify, and manipulate Google Slides presentations programmatically.

Installation
Credential Setup
Server Startup
Tool Reference
Output Formats
Configuration
Troubleshooting

Installation

Install gslides-api with the MCP extra:

pip install gslides-api[mcp]
# or with poetry
poetry add gslides-api -E mcp

Credential Setup

See CREDENTIALS.md for detailed instructions on setting up Google API credentials.

Server Startup

Command Line

# Using the CLI argument
python -m gslides_api.mcp.server --credential-path /path/to/credentials

# Using environment variable
export GSLIDES_CREDENTIALS_PATH=/path/to/credentials
python -m gslides_api.mcp.server

# With custom default output format
python -m gslides_api.mcp.server --credential-path /path/to/credentials --default-format outline

# Using the installed script
gslides-mcp --credential-path /path/to/credentials

CLI Arguments

Argument	Description	Default
`--credential-path`	Path to Google API credentials directory	`GSLIDES_CREDENTIALS_PATH` env var
`--default-format`	Default output format: `raw`, `domain`, or `outline`	`raw`

Environment Variables

Variable	Description
`GSLIDES_CREDENTIALS_PATH`	Alternative to `--credential-path` (CLI arg takes precedence)

MCP Configuration (`.mcp.json`)

Add to your .mcp.json configuration:

{
  "gslides": {
    "type": "stdio",
    "command": "python",
    "args": ["-m", "gslides_api.mcp.server"]
  }
}

The server reads credentials from the GSLIDES_CREDENTIALS_PATH environment variable. Use --credential-path to override:

{
  "gslides": {
    "type": "stdio",
    "command": "python",
    "args": ["-m", "gslides_api.mcp.server", "--credential-path", "/path/to/credentials"]
  }
}

Tool Reference

Query Tools

`get_presentation`

Get a full presentation by URL or deck ID.

Arguments:

Name	Type	Required	Default	Description
`presentation_id_or_url`	string	Yes	-	Google Slides URL or presentation ID
`how`	string	No	Server default	Output format: `raw`, `domain`, or `outline`

Example:

{
  "presentation_id_or_url": "https://docs.google.com/presentation/d/1abc123/edit",
  "how": "outline"
}

`get_slide`

Get a single slide by name (first line of speaker notes).

Arguments:

Name	Type	Required	Default	Description
`presentation_id_or_url`	string	Yes	-	Google Slides URL or presentation ID
`slide_name`	string	Yes	-	Slide name (first line of speaker notes)
`how`	string	No	Server default	Output format: `raw`, `domain`, or `outline`

Example:

{
  "presentation_id_or_url": "1abc123",
  "slide_name": "Introduction",
  "how": "domain"
}

`get_element`

Get a single element by slide name and element name (alt-title).

Arguments:

Name	Type	Required	Default	Description
`presentation_id_or_url`	string	Yes	-	Google Slides URL or presentation ID
`slide_name`	string	Yes	-	Slide name
`element_name`	string	Yes	-	Element name (from alt-text title)
`how`	string	No	Server default	Output format

`get_slide_thumbnail`

Get a slide thumbnail image, optionally with black borders around text boxes.

Arguments:

Name	Type	Required	Default	Description
`presentation_id_or_url`	string	Yes	-	Google Slides URL or presentation ID
`slide_name`	string	Yes	-	Slide name
`add_text_box_borders`	boolean	No	`false`	Add 1pt black outlines to text boxes
`size`	string	No	`LARGE`	Thumbnail size: `SMALL` (200px), `MEDIUM` (800px), `LARGE` (1600px)

Returns: JSON with base64-encoded PNG image data.

Example Response:

{
  "success": true,
  "slide_name": "Introduction",
  "slide_id": "p1",
  "width": 1600,
  "height": 900,
  "mime_type": "image/png",
  "image_base64": "iVBORw0KGgo..."
}

Markdown Tools

`read_element_markdown`

Read the text content of a shape element as markdown.

Arguments:

Name	Type	Required	Default	Description
`presentation_id_or_url`	string	Yes	-	Google Slides URL or presentation ID
`slide_name`	string	Yes	-	Slide name
`element_name`	string	Yes	-	Element name (text box alt-title)

Returns: Markdown content preserving bold, italic, bullets, etc.

`write_element_markdown`

Write markdown content to a shape element (text box).

Arguments:

Name	Type	Required	Default	Description
`presentation_id_or_url`	string	Yes	-	Google Slides URL or presentation ID
`slide_name`	string	Yes	-	Slide name
`element_name`	string	Yes	-	Element name (text box alt-title)
`markdown`	string	Yes	-	Markdown content to write

Image Tools

`replace_element_image`

Replace an image element with a new image from URL.

Arguments:

Name	Type	Required	Default	Description
`presentation_id_or_url`	string	Yes	-	Google Slides URL or presentation ID
`slide_name`	string	Yes	-	Slide name
`element_name`	string	Yes	-	Element name (image alt-title)
`image_url`	string	Yes	-	URL of new image

Slide Manipulation Tools

`copy_slide`

Duplicate a slide within the presentation.

Arguments:

Name	Type	Required	Default	Description
`presentation_id_or_url`	string	Yes	-	Google Slides URL or presentation ID
`slide_name`	string	Yes	-	Slide name to copy
`insertion_index`	integer	No	After original	Position for new slide (0-indexed)

Returns: New slide info including new_slide_id.

`move_slide`

Move a slide to a new position in the presentation.

Arguments:

Name	Type	Required	Default	Description
`presentation_id_or_url`	string	Yes	-	Google Slides URL or presentation ID
`slide_name`	string	Yes	-	Slide name to move
`insertion_index`	integer	Yes	-	New position (0-indexed)

`delete_slide`

Delete a slide from the presentation.

Arguments:

Name	Type	Required	Default	Description
`presentation_id_or_url`	string	Yes	-	Google Slides URL or presentation ID
`slide_name`	string	Yes	-	Slide name to delete

Output Formats

The how parameter controls the output format for query tools:

`raw`

Returns the raw JSON response from the Google Slides API. Most verbose, includes all API fields.

{
  "presentationId": "1abc123",
  "title": "My Presentation",
  "slides": [...],
  "masters": [...],
  "layouts": [...]
}

`domain`

Returns the gslides-api domain object serialized via model_dump(). Structured Pydantic models with Python-friendly field names.

{
  "presentationId": "1abc123",
  "title": "My Presentation",
  "slides": [...],
  "pageSize": {"width": {...}, "height": {...}}
}

`outline`

Returns a condensed structure optimized for AI consumption. Includes slide names, element names, alt-descriptions, and text content as markdown.

{
  "presentation_id": "1abc123",
  "title": "My Presentation",
  "slides": [
    {
      "slide_name": "Introduction",
      "slide_id": "p1",
      "elements": [
        {
          "element_name": "Title",
          "element_id": "e1",
          "type": "shape",
          "alt_description": "Main title",
          "content_markdown": "# Welcome to the Presentation"
        },
        {
          "element_name": "Hero Image",
          "element_id": "e2",
          "type": "image",
          "alt_description": "Company logo"
        }
      ]
    }
  ]
}

Slide and Element Naming

Slide Names

Slide names are derived from the first line of the speaker notes, stripped of whitespace. If a slide has no speaker notes or the first line is empty, it cannot be referenced by name (use the outline format to discover slide IDs).

Element Names

Element names come from the alt-text title of each element. In Google Slides:

Right-click an element
Select "Alt text"
Enter a name in the "Title" field

Elements without alt-text titles cannot be referenced by name.

Error Handling

All tools return detailed error responses when failures occur:

{
  "error": true,
  "error_type": "SlideNotFound",
  "message": "No slide found with name 'Introduction'",
  "details": {
    "presentation_id": "1abc123",
    "searched_slide_name": "Introduction",
    "available_slides": ["Cover", "Overview", "Conclusion"]
  }
}

Error Types

Error Type	Description
`ValidationError`	Invalid input parameter
`SlideNotFound`	Specified slide name not found
`ElementNotFound`	Specified element name not found on slide
`PresentationError:*`	Google API error (includes specific exception type)

Troubleshooting

"API client not initialized"

Ensure you've provided a valid credential path via --credential-path or the GSLIDES_CREDENTIALS_PATH environment variable.

OAuth flow opens repeatedly

Delete token.json in your credentials directory and re-authenticate.

"Rate limit exceeded"

The server implements exponential backoff for rate limits. If you continue to see errors, reduce the frequency of API calls.

Slide/Element not found

Use get_presentation with how=outline to see all available slide and element names
Ensure slides have speaker notes with content on the first line
Ensure elements have alt-text titles set

Import errors for MCP

Ensure you've installed the MCP extra:

pip install gslides-api[mcp]

FilesExpand file tree

MCP_SERVER.md

Latest commit

History

MCP_SERVER.md

File metadata and controls

gslides-api MCP Server

Table of Contents

Installation

Credential Setup

Server Startup

Command Line

CLI Arguments

Environment Variables

MCP Configuration (.mcp.json)

Tool Reference

Query Tools

get_presentation

get_slide

get_element

get_slide_thumbnail

Markdown Tools

read_element_markdown

write_element_markdown

Image Tools

replace_element_image

Slide Manipulation Tools

copy_slide

move_slide

delete_slide

Output Formats

raw

domain

outline

Slide and Element Naming

Slide Names

Element Names

Error Handling

Error Types

Troubleshooting

"API client not initialized"

OAuth flow opens repeatedly

"Rate limit exceeded"

Slide/Element not found

Import errors for MCP

MCP Configuration (`.mcp.json`)

`get_presentation`

`get_slide`

`get_element`

`get_slide_thumbnail`

`read_element_markdown`

`write_element_markdown`

`replace_element_image`

`copy_slide`

`move_slide`

`delete_slide`

`raw`

`domain`

`outline`