PowerPoint MCP Tools
This project provides MCP (Model Context Protocol) tools for converting PowerPoint presentations to/from structured JSON format using Pydantic models.
MCP Server Configuration
To use this project as an MCP server in external applications, add the following configuration to your mcpServers configuration:
Method 1: From GitHub Repository (Recommended)
Install directly from GitHub - no local setup required:
{
"mcpServers": {
"mcp-powerpoint": {
"command": "uvx",
"args": ["--from", "git+https://github.com/CannonJunior/mcp-powerpoint.git", "mcp-powerpoint", "--server", "powerpoint"],
"env": {}
},
"mcp-shape-naming": {
"command": "uvx",
"args": ["--from", "git+https://github.com/CannonJunior/mcp-powerpoint.git", "mcp-powerpoint", "--server", "shape-naming"],
"env": {}
}
}
}
Method 2: From PyPI (When Published)
Once published to PyPI, you can use the simple form:
{
"mcpServers": {
"mcp-powerpoint": {
"command": "uvx",
"args": ["mcp-powerpoint", "--server", "powerpoint"],
"env": {}
},
"mcp-shape-naming": {
"command": "uvx",
"args": ["mcp-powerpoint", "--server", "shape-naming"],
"env": {}
}
}
}
Method 3: Local Development
For local development, you can use uv directly:
{
"mcpServers": {
"mcp-powerpoint": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp-powerpoint",
"run",
"-m",
"mcp_powerpoint",
"--server",
"powerpoint"
],
"env": {}
},
"mcp-shape-naming": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp-powerpoint",
"run",
"-m",
"mcp_powerpoint",
"--server",
"shape-naming"
],
"env": {}
}
}
}
Quick Start
- Install uvx:
curl -LsSf https://astral.sh/uv/install.sh | sh - Copy the configuration from
mcp-config.jsonto your MCP client settings - For shape naming: Install Ollama and pull a model:
ollama pull llama3.2 - That's it! - uvx installs from GitHub automatically
Test the installation:
uvx --from git+https://github.com/CannonJunior/mcp-powerpoint.git mcp-powerpoint --help
Prerequisites
- UV/UVX: Required for running the servers (
curl -LsSf https://astral.sh/uv/install.sh | sh) - Ollama (shape naming only): Install from https://ollama.ai and run
ollama pull llama3.2 - No Python setup required - uvx manages everything in isolated environments!
Testing the Configuration
To verify the MCP servers are working correctly:
-
Test from GitHub:
# Test PowerPoint server uvx --from git+https://github.com/CannonJunior/mcp-powerpoint.git mcp-powerpoint --server powerpoint # Test shape naming server uvx --from git+https://github.com/CannonJunior/mcp-powerpoint.git mcp-powerpoint --server shape-naming
-
For local development:
cd /path/to/mcp-powerpoint uv run -m mcp_powerpoint --server powerpoint # In another terminal: uv run -m mcp_powerpoint --server shape-naming
-
Check that they respond to MCP protocol messages and expose the expected tools:
- PowerPoint server:
pptx_to_json,json_to_pptx - Shape naming server:
analyze_shape_content,generate_descriptive_names_for_presentation
- PowerPoint server:
Features
- Complete PowerPoint Analysis: Extracts all text, shapes, images, tables, positioning, and formatting
- Intelligent Shape Naming: Uses Ollama LLM to generate descriptive names based on content
- Pydantic Models: Type-safe data structures for PowerPoint objects
- Roundtrip Conversion: Original PPTX → JSON → New PPTX with high fidelity
- Multiple Client Modes: Basic demo, extract, refine, rename, and populate workflows
- MCP Integration: Works with any MCP-compatible client
Files
Core Components
powerpoint_models.py- Comprehensive Pydantic models for PowerPoint structurepowerpoint_server.py- MCP server providing PowerPoint conversion toolsshape_naming_server.py- MCP server for generating descriptive shape names using Ollamaclient.py- Basic demo client showing PowerPoint and Shape Naming integrationclient_modes.py- Advanced multi-mode client for specialized workflows
PowerPoint Conversion Tools
pptx_to_json(file_path: str) -> str
Converts a PowerPoint file to structured JSON format.
- Extracts all slides, shapes, text content, formatting, images, and tables
- Preserves positioning, sizing, fonts, colors, and other properties
- Returns comprehensive JSON representation
json_to_pptx(json_data: str, output_path: str) -> str
Creates a PowerPoint file from JSON data.
- Reconstructs slides, shapes, text, images, and tables
- Applies formatting, positioning, and styling
- Generates a new .pptx file
Shape Naming Tools (via Ollama)
analyze_shape_content(shape_name: str, shape_text: str, shape_type: str) -> str
Analyzes individual shape content and generates descriptive names.
- Uses Ollama LLM to analyze text content
- Generates programmatic names (lowercase with underscores)
- Examples: "Rectangle 5" → "company_header", "TextBox 42" → "project_title"
generate_descriptive_names_for_presentation(json_data: str) -> str
Processes entire presentations to rename all shapes.
- Batch processes all shapes in a presentation
- Handles duplicate names with numbering
- Returns updated JSON with
descriptive_nameandoriginal_namefields
get_shape_suggestions(shape_text: str, context: str = "") -> str
Provides multiple naming suggestions with rationales.
- Returns 3 different naming options
- Includes rationale for each suggestion
- Useful for manual shape naming decisions
batch_rename_shapes(json_data: str, naming_rules: str = "") -> str
Advanced batch renaming with custom rules.
- Supports rule-based renaming patterns
- Falls back to automatic naming for unmatched shapes
- Returns detailed rename operation results
Usage
1. Python Client Options
Basic Demo Client
Run the basic client for a comprehensive demo of both PowerPoint and Shape Naming tools:
uv run client.py
This client will:
- Convert a PowerPoint to JSON
- Generate descriptive names for all shapes using Ollama
- Recreate the PowerPoint from JSON
- Save results to
presentation_with_descriptive_names.json
Advanced Multi-Mode Client
The client_modes.py provides specialized modes for different workflows:
Extract Mode - Convert PowerPoint to JSON and recreate:
python client_modes.py extract -i input.pptx
python client_modes.py extract -i input.pptx --json output.json --pptx recreated.pptx
Refine Mode - Improve recreated PowerPoint presentations:
python client_modes.py refine -i recreated.pptx
Rename Mode - Generate descriptive shape names with document analysis:
python client_modes.py rename -i presentation.json --content-dir ./docs
Populate Mode - Create presentations from templates using document content:
python client_modes.py populate -i template.pptx --naming-json names.json --content-dir ./content
2. Direct MCP Server Usage
Start the PowerPoint MCP Server
python powerpoint_server.py
Start the Shape Naming MCP Server
python shape_naming_server.py
3. MCP Tool Integration
# Convert PowerPoint to JSON
json_result = await client.call_tool("powerpoint_pptx_to_json", {
"file_path": "presentation.pptx"
})
# Convert JSON back to PowerPoint
pptx_result = await client.call_tool("powerpoint_json_to_pptx", {
"json_data": json_string,
"output_path": "output.pptx"
})
# Generate descriptive names for all shapes
naming_result = await client.call_tool("shape_naming_generate_descriptive_names_for_presentation", {
"json_data": json_string
})
# Analyze individual shape content
shape_name = await client.call_tool("shape_naming_analyze_shape_content", {
"shape_name": "Rectangle 5",
"shape_text": "General Atomics – Integrated Intelligence, Inc.",
"shape_type": "AUTO_SHAPE"
})
Data Structure
The JSON structure captures:
- Presentation: Dimensions, properties, metadata
- Slides: Individual slide content and properties
- Shapes: All shape types (text boxes, auto shapes, images, tables)
- Text: Formatted text with fonts, colors, styling
- Images: Base64-encoded image data with cropping info
- Tables: Complete table structure with cell content
- Positioning: Exact coordinates and dimensions
- Formatting: Colors, fonts, line styles, fills
Test Results
Successfully tested with MDA-250083-BNB-20250904.v1.RFI.pptx:
- Original file: 132,823 bytes
- JSON representation: 158,917 bytes
- Recreated file: 61,334 bytes
- ✅ Roundtrip conversion successful
- ✅ All text content preserved
- ✅ Font sizes correctly extracted (12pt, 14pt) and applied
- ✅ Font colors extracted (
#000000,#FFFFFF) and applied - ✅ Shape fill colors extracted (
#D6D6D6,#000000) and applied - ✅ Shape border colors extracted (
#000000) and applied - ✅ Shape positioning maintained
- ✅ Image data captured and restored
Fixed Issues
- Font Size Accuracy: Fixed EMU to points conversion (was showing 177800, now correctly shows 12pt)
- Font Color Extraction: Properly handles RGBColor objects with hex output
- Shape Fill Colors: Extracts solid, gradient, and patterned fill colors correctly
- Shape Border Colors: Extracts line colors, widths, and dash styles with proper RGBColor handling
- Color Application: Applies fill and border colors during PowerPoint reconstruction
Dependencies
python-pptx- PowerPoint file manipulationpydantic- Data models and JSON serializationfastmcp- MCP server frameworkpillow- Image processingbase64- Image encoding/decodingollama- Local LLM integration for shape naminguv- Fast Python package manager (recommended)
Architecture
The system uses a three-layer architecture:
- Pydantic Models - Type-safe data structures
- Extraction Layer - Converts PowerPoint objects to models
- Reconstruction Layer - Rebuilds PowerPoint from models
- MCP Interface - Exposes functionality as tools
This enables reliable, type-safe conversion between PowerPoint files and structured JSON data suitable for analysis, modification, or storage.
Metadata
Release files for mcp-powerpoint 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcp_powerpoint-1.0.0.tar.gz | 20.0 kB | With provenance | Details for mcp_powerpoint-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_powerpoint-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for mcp_powerpoint-1.0.0-py3-none-any.whl |
Total release size: 38.1 kB
Release files / mcp_powerpoint-1.0.0.tar.gz
| Download URL | mcp_powerpoint-1.0.0.tar.gz |
|---|---|
| Size | 20.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
23e905d08586a22e13de885eb5b83409740cd952ae612c81579f7c4ac7ea69d4
|
|
BLAKE2b-256 checksum How to use checksums |
f9392ec1bcec4b2bedd8fd475fd29af81bc7c8a058612030ddb4a2a3cf95adc2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 21, 2025.
Transparency logRelease files / mcp_powerpoint-1.0.0-py3-none-any.whl
| Download URL | mcp_powerpoint-1.0.0-py3-none-any.whl |
|---|---|
| Size | 18.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a45ece6948a4375d6a4e96abc7355235c435be25263d6b41497048f129be6571
|
|
BLAKE2b-256 checksum How to use checksums |
eb6e2c96f25b205d01b52e56732a454040d31adab8711c491e11dd428f290a93
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 21, 2025.
Transparency logSecurity for mcp-powerpoint 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for mcp_powerpoint-1.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 21, 2025.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.