🎯 PPT-MCP
Pure Node.js PowerPoint MCP Server - Create, analyze, and manage PowerPoint presentations with AI assistance
✨ 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
🚀 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 titleslides(optional) - Number of slides (default: 1)output_path(optional) - Custom save locationtemplate(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 presentationoperation(required) - Edit type:add_slide,add_text,add_image,add_tableslide_index(optional) - Target slide numbercontent(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 presentationoperation(required) - Operation type:get_guidance,add_slide,replace_text,extract_contentslide_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 fileoutput_format(optional) - Format:text,json,markdownslide_range(optional) - Specific slides to readinclude_notes(optional) - Include speaker notes
4. analyze_presentation
Perform comprehensive analysis of presentation structure and content.
Parameters:
file_path(required) - Path to presentation fileanalysis_type(optional) - Analysis type:structure,content,statistics,readability,comprehensivedetailed(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_enhancedtool 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:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - 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
- 🌐 LinkedIn: Xingyu Chen
- 📧 Email: guangxiangdebizi@gmail.com
- 🐙 GitHub: @guangxiangdebizi
- 📦 NPM: @xingyuchen
🙏 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!