gslides-api

A Python library for working with Google Slides API using Pydantic domain objects.

Overview

This library provides a Pythonic interface to the Google Slides API with:

• Pydantic domain objects that match the JSON structure returned by the Google Slides API
• Type-safe operations with full type hints support
• Easy-to-use methods for creating, reading, and manipulating Google Slides presentations
• Comprehensive coverage of Google Slides API features

Installation

pip install gslides-api

Quick Start

Authentication

First, set up your Google API credentials. See CREDENTIALS.md for detailed instructions.

from gslides_api import initialize_credentials

# Initialize with your credentials directory
initialize_credentials("/path/to/your/credentials/")

Basic Usage

from gslides_api import Presentation

# Load an existing presentation
presentation = Presentation.from_id("your-presentation-id")

# Create a new blank presentation
new_presentation = Presentation.create_blank("My New Presentation")

# Access slides
for slide in presentation.slides:
    print(f"Slide ID: {slide.objectId}")
    
# Create a new slide
new_slide = presentation.add_slide()

Features

• Domain Objects: Complete Pydantic models for all Google Slides API objects
• Presentations: Create, load, copy, and manipulate presentations
• Slides: Add, remove, duplicate, and reorder slides
• Elements: Work with text boxes, shapes, images, and other slide elements
• Layouts: Access and use slide layouts and masters
• Requests: Type-safe request builders for batch operations
• Markdown Support: Convert between Markdown and Google Slides content
• MCP Server: Expose Google Slides operations as tools for AI assistants

MCP Server

gslides-api includes an MCP (Model Context Protocol) server that exposes Google Slides operations as tools for AI assistants like Claude.

Installation

pip install gslides-api[mcp]

Quick Start

# Set credentials path
export GSLIDES_CREDENTIALS_PATH=/path/to/credentials

# Run the MCP server
python -m gslides_api.mcp.server

Available Tools

Tool	Description
get_presentation	Get full presentation by URL or ID
get_slide	Get slide by name (speaker notes)
get_element	Get element by slide and element name
get_slide_thumbnail	Get slide thumbnail image
read_element_markdown	Read text element as markdown
write_element_markdown	Write markdown to text element
replace_element_image	Replace image from URL
copy_slide	Duplicate a slide
move_slide	Reorder slide position
delete_slide	Remove a slide

MCP Configuration

Add to your .mcp.json:

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

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

See docs/MCP_SERVER.md for detailed documentation.

API Coverage

The library covers most Google Slides API functionality including:

• Presentations and slides management
• Text elements and formatting
• Shapes and images
• Tables and charts
• Page layouts and masters
• Batch update operations

Requirements

• Python 3.8+
• Google API credentials (OAuth2 or Service Account)

Dependencies

• google-api-python-client - Google API client library
• google-auth-oauthlib - OAuth2 authentication
• pydantic - Data validation and serialization
• marko - Markdown processing
• protobuf - Protocol buffer support

Development

Running Tests

pip install -e ".[test]"
pytest

Code Formatting

pip install -e ".[dev]"
black gslides_api/
isort gslides_api/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• md2googleslides - TypeScript library for creating slides from Markdown
• gslides - Python library focused on charts and tables
• gslides-maker - Generate slides from Wikipedia content

Acknowledgments

This library is built on top of the excellent Google API Python client and leverages the power of Pydantic for type-safe data handling.