Skip to main content
Glama
guangxiangdebizi

PPT-MCP

by guangxiangdebizi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

🎯 PPT-MCP

Pure Node.js PowerPoint MCP Server - Create, analyze, and manage PowerPoint presentations with AI assistance

1 PPT-MCP is a Model Context Protocol (MCP) server that provides comprehensive PowerPoint presentation management capabilities using pure JavaScript/TypeScript. Built with PptxGenJS, the most popular PowerPoint library for Node.js with 3,500+ GitHub stars.

✨ Features

🚀 Pure Node.js Stack

  • Zero Python Dependencies - 100% JavaScript/TypeScript implementation

  • Cross-Platform - Works on Windows, macOS, and Linux

  • Modern Architecture - Built with latest Node.js and TypeScript

  • Lightweight - Minimal dependencies, fast startup

📊 Core Capabilities

  • 🎨 Create Presentations - Generate professional PowerPoint files with custom templates

  • ✏️ Edit Existing Files - Advanced editing capabilities with pptx-automizer for real PowerPoint modification

  • 📖 File Analysis - Analyze presentation structure and metadata

  • 🔧 Template Support - Basic, Professional, and Modern design templates

  • 📁 File Management - Smart file handling and directory management

🎯 AI-Powered Workflow

  • Claude Integration - Seamless integration with Claude Desktop

  • Natural Language - Create presentations using conversational commands

  • Intelligent Templates - AI-suggested layouts and designs

  • Batch Operations - Handle multiple presentations efficiently

Related MCP server: Deckbuilder MCP Server

🚀 Quick Start

Prerequisites

  • Node.js 18+

  • Claude Desktop (for MCP integration)

Installation

Option 1: NPM Package (Recommended)

npm install -g ppt-mcp

Option 2: From Source

git clone https://github.com/guangxiangdebizi/PPT-MCP.git
cd PPT-MCP
npm install
npm run build

Claude Desktop Configuration

Add to your Claude Desktop config:

Stdio Mode (Local Development)

{
  "mcpServers": {
    "ppt-mcp": {
      "command": "node",
      "args": ["path/to/PPT-MCP/build/index.js"]
    }
  }
}

SSE Mode (Production)

# Install and run with Supergateway
npm install -g supergateway
npx supergateway --stdio "node build/index.js" --port 3100
{
  "mcpServers": {
    "ppt-mcp": {
      "type": "sse",
      "url": "http://localhost:3100/sse",
      "timeout": 600
    }
  }
}

🛠️ Available Tools

1. create_presentation

Create new PowerPoint presentations with customizable options.

Parameters:

  • title (required) - Presentation title

  • slides (optional) - Number of slides (default: 1)

  • output_path (optional) - Custom save location

  • template (optional) - Design template: basic, professional, modern

Example:

Create a presentation titled "Q4 Business Review" with 5 slides using the professional template

2. edit_presentation

Basic editing of existing presentations (Note: Limited by PptxGenJS library capabilities).

Parameters:

  • file_path (required) - Path to existing presentation

  • operation (required) - Edit type: add_slide, add_text, add_image, add_table

  • slide_index (optional) - Target slide number

  • content (optional) - Content to add

2.5. edit_presentation_enhanced 🆕

Enhanced PowerPoint editing with comprehensive guidance and step-by-step instructions for manual editing.

Parameters:

  • file_path (required) - Path to existing presentation

  • operation (required) - Operation type: get_guidance, add_slide, replace_text, extract_content

  • slide_index (optional) - Target slide number (1-based)

  • content (optional) - Content specifications

Features:

  • 📋 Step-by-step editing instructions

  • 🔧 Multiple solution approaches

  • 💡 Best practice recommendations

  • 🎯 Operation-specific guidance

Example:

Get guidance for editing "report.pptx" to replace text content

3. read_presentation

Analyze and extract information from PowerPoint files.

Parameters:

  • file_path (required) - Path to presentation file

  • output_format (optional) - Format: text, json, markdown

  • slide_range (optional) - Specific slides to read

  • include_notes (optional) - Include speaker notes

4. analyze_presentation

Perform comprehensive analysis of presentation structure and content.

Parameters:

  • file_path (required) - Path to presentation file

  • analysis_type (optional) - Analysis type: structure, content, statistics, readability, comprehensive

  • detailed (optional) - Enable detailed analysis

📁 Project Structure

PPT-MCP/
├── src/
│   ├── index.ts              # MCP server entry point
│   └── tools/
│       ├── ppt-creator.ts     # Creation & editing tools
│       └── ppt-reader.ts      # Reading & analysis tools
├── build/                     # Compiled JavaScript
├── package.json              # Dependencies & scripts
├── tsconfig.json             # TypeScript configuration
├── README.md                 # Documentation
└── LICENSE                   # Apache 2.0 License

🔧 Development

Build Commands

npm run build        # Compile TypeScript
npm run dev          # Watch mode compilation
npm start           # Run compiled server
npm run sse         # Start with Supergateway SSE

Testing

# Test server startup
node build/index.js

# Test presentation creation
# (Use Claude Desktop or MCP client)

🎨 Template Showcase

Basic Template

  • Clean, minimal design

  • Black text on white background

  • Perfect for academic or simple business presentations

Professional Template

  • Corporate color scheme (Dark Slate Gray)

  • Sophisticated typography

  • Ideal for business meetings and reports

Modern Template

  • Vibrant blue and green accents

  • Contemporary design elements

  • Great for creative and tech presentations

🚀 Technology Stack

  • Runtime: Node.js 18+

  • Language: TypeScript

  • PPT Engine: 1 PptxGenJS (3,500+ ⭐)

  • MCP SDK: @modelcontextprotocol/sdk

  • Build System: TypeScript Compiler

  • Package Manager: NPM

🔄 Migration from Python

This version represents a complete rewrite from Python to pure Node.js:

Advantages of Node.js Version:

  • ✅ Faster Startup - No Python interpreter overhead

  • ✅ Simpler Deployment - Single runtime environment

  • ✅ Better Integration - Native JavaScript ecosystem

  • ✅ Modern Tooling - TypeScript, ESM, and modern Node.js features

  • ✅ Cross-Platform - Consistent behavior across operating systems

Current Limitations:

  • ⚠️ Direct File Modification - PptxGenJS is creation-focused, not editing-focused

  • ⚠️ Complex Animations - Advanced animations not yet supported

  • ⚠️ Embedded Media - Video/audio embedding requires additional implementation

Solutions Provided:

  • ✅ Comprehensive Guidance - edit_presentation_enhanced tool provides step-by-step instructions

  • ✅ Multiple Approaches - Manual editing, hybrid workflows, and programmatic creation

  • ✅ Best Practices - Detailed recommendations for different editing scenarios

The edit_presentation_enhanced tool bridges the gap by providing expert guidance for PowerPoint editing workflows.

🤝 Contributing

We welcome contributions! Here's how to get started:

  1. Fork the repository

  2. Create a feature branch: git checkout -b feature/amazing-feature

  3. Commit your changes: git commit -m 'Add amazing feature'

  4. Push to the branch: git push origin feature/amazing-feature

  5. Open a Pull Request

Development Guidelines

  • Follow TypeScript best practices

  • Add tests for new features

  • Update documentation

  • Ensure cross-platform compatibility

📄 License

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

👨‍💻 Author

Xingyu Chen

🙏 Acknowledgments

  • PptxGenJS Team - For the excellent PowerPoint generation library

  • Anthropic - For the Model Context Protocol specification

  • TypeScript Team - For the amazing type system

  • Node.js Community - For the robust runtime environment

⭐ Star this repo if you find it helpful!

🐛 Report Bug • ✨ Request Feature • 📖 Documentation

Available Tools

4 tools
analyze_presentationC

Analyze PowerPoint presentation structure, content, and provide insights

ParametersJSON Schema
NameRequiredDescriptionDefault
analysis_typeNoType of analysis to performcomprehensive
detailedNoWhether to provide detailed analysis
file_pathYesPath to the PowerPoint file to analyze

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'analyze' and 'provide insights', which imply a read-only operation, but doesn't clarify if it modifies the file, requires specific permissions, or has limitations like file size or format. For a tool with no annotation coverage, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded, consisting of a single sentence that directly states the tool's purpose. There's no wasted language or redundancy, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (analyzing presentations with multiple parameters) and the lack of annotations and output schema, the description is incomplete. It doesn't cover behavioral aspects like whether the tool is read-only, what insights are provided, or how results are returned. This leaves users with insufficient information to use the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description doesn't add meaning beyond the input schema, which has 100% coverage. It mentions 'structure, content, and provide insights', which loosely relates to the 'analysis_type' parameter but doesn't explain the semantics of parameters like 'detailed' or 'file_path'. With high schema coverage, the baseline is 3, as the schema adequately documents the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Analyze PowerPoint presentation structure, content, and provide insights.' It specifies the verb ('analyze'), resource ('PowerPoint presentation'), and scope ('structure, content, and insights'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'read_presentation' or 'edit_presentation', which might also involve analyzing content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'read_presentation' or 'edit_presentation', nor does it specify prerequisites, such as needing an existing PowerPoint file. Without this context, users might struggle to choose between similar tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_presentationC

Create a new PowerPoint presentation with specified title and number of slides

ParametersJSON Schema
NameRequiredDescriptionDefault
output_pathNoOutput file path (optional, defaults to current directory)
slidesNoNumber of slides to create (default: 1)
templateNoPresentation template stylebasic
titleYesTitle of the presentation

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool creates a presentation but doesn't mention critical aspects like whether it overwrites existing files, requires authentication, has rate limits, or what the output looks like (e.g., file format, success indicators). This leaves significant gaps for an agent to understand the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. Every part of the sentence contributes directly to understanding the tool's function, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a creation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens upon execution (e.g., file creation, error handling), return values, or behavioral constraints. For a tool that modifies the system by creating files, more context is needed to ensure safe and effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description mentions 'title and number of slides', which aligns with two of the four parameters in the schema. However, with 100% schema description coverage, the schema already fully documents all parameters, including 'output_path' and 'template' with their defaults and options. The description adds minimal value beyond what's in the schema, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Create a new PowerPoint presentation') and specifies the key inputs ('with specified title and number of slides'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'edit_presentation' or 'read_presentation' beyond the creation aspect, which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'edit_presentation' or 'read_presentation'. It lacks context about prerequisites, such as whether it requires specific software or permissions, or when it's appropriate for initial creation versus modification.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

edit_presentationC

Edit an existing PowerPoint presentation by adding slides or modifying content

ParametersJSON Schema
NameRequiredDescriptionDefault
contentNoContent to add based on operation type
file_pathYesPath to the existing presentation file
operationYesType of edit operation
slide_indexNoSlide index to edit (1-based, optional for add_slide)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states this is an edit operation but doesn't describe what 'edit' entails—whether it modifies the original file or creates a copy, what permissions are needed, error handling, or side effects. This is inadequate for a mutation tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core purpose. It avoids unnecessary words, though it could be slightly more structured by separating operation types more clearly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., file modification behavior, error cases), usage context, and output expectations, leaving significant gaps for an agent to understand how to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds no additional parameter semantics beyond implying that 'edit' involves operations like adding slides or modifying content, which aligns with the operation enum. Baseline 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('edit') and resource ('existing PowerPoint presentation') with specific operations ('adding slides or modifying content'). It distinguishes from siblings like create_presentation (new vs. existing) and read_presentation/analyze_presentation (edit vs. read/analyze), though it doesn't explicitly name these distinctions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like create_presentation or analyze_presentation. It mentions 'existing PowerPoint presentation' which implies it's for editing rather than creating, but offers no explicit when/when-not rules or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_presentationB

Read and extract content from PowerPoint presentations

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYesPath to the PowerPoint file to read
include_notesNoWhether to include speaker notes
output_formatNoOutput format for the contenttext
slide_rangeNoRange of slides to read (optional)

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool reads and extracts content, implying a read-only operation, but doesn't address critical aspects like error handling (e.g., invalid file paths), performance expectations, or whether it modifies the original file. This leaves significant gaps in understanding the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It's front-loaded with the core purpose ('read and extract content'), making it easy to grasp quickly. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (4 parameters, nested objects) and lack of annotations or output schema, the description is minimally adequate but incomplete. It covers the basic purpose but fails to address behavioral traits, usage context, or output details, leaving the agent to rely heavily on the schema for operational understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, meaning all parameters are well-documented in the schema itself. The description adds no additional semantic context beyond what's already in the schema (e.g., it doesn't explain how 'output_format' affects readability or why 'slide_range' is optional). This meets the baseline for high schema coverage but doesn't enhance parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('read and extract content') and resource ('PowerPoint presentations'), making the tool's purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'analyze_presentation' or 'edit_presentation', which might have overlapping functionality with content extraction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'analyze_presentation' or 'create_presentation'. There's no mention of prerequisites, such as file accessibility, or when this tool is preferred over others for content extraction tasks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.0
    • First observedanalyze_presentation
    • First observedcreate_presentation
    • First observededit_presentation
    • First observedread_presentation
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: analyze for insights, create for new presentations, edit for modifications, and read for content extraction. There is no overlap in functionality, making tool selection straightforward for an agent.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (e.g., analyze_presentation, create_presentation), using snake_case throughout. This predictability enhances readability and usability for agents.

Tool Count5/5

With 4 tools, the server is well-scoped for PowerPoint presentation management. Each tool serves a distinct and essential function (create, read, edit, analyze), with no unnecessary or redundant tools, making the count appropriate for the domain.

Completeness4/5

The toolset covers core CRUD-like operations (create, read, edit) and analysis, providing a solid foundation for presentation workflows. A minor gap exists in deletion or more advanced editing features, but agents can work effectively with the current tools.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches