keynote-mcp is a Model Context Protocol (MCP) server that enables AI assistants to control Keynote presentations through AppleScript automation. It supports creating, editing, and exporting presentations using natural language.
Main capabilities
- Full control of Apple Keynote through AppleScript automation.
- Create, edit, and export presentations.
- Provides more than 30 available tools.
- Optional Unsplash image integration.
- Includes the keynote-presentation skill (Claude Skill), which encodes layout rules, font avoidance methods, and design patterns so that presentations are generated correctly the first time.
Usage Prerequisite: Keynote app is installed. Installation methods:
- Method A: Install from PyPI, or run directly with uvx (no installation required).
- Method B: Install from source. Register the MCP server:
- Claude Code (PyPI install / uvx)
- Claude Code (from source)
- Claude Desktop: Add to claude_desktop_config.json, or use uvx.
- Other MCP clients: The command is keynote-mcp (if installed via pip) or uvx keynote-mcp; the transport is stdio. Install the skill (recommended):
- The keynote-presentation skill teaches Claude how to correctly use the MCP tools, handle the font clipping bug, theme pitfalls, coordinate calculations, and design patterns.
- Claude Code: Copy the skill folder to the skills directory.
- Package the skills/keynote-presentation folder as a zip, go to Settings > Capabilities > Skills, click “Upload skill” and select the zip. macOS permissions:
- System Settings > Privacy & Security > Accessibility — add Terminal/your IDE.
- System Settings > Privacy & Security > Automation — allow Python to control Keynote.
- Security note: Accessibility permissions are per binaryGranted, not per-project. Once the python accessibility permission is granted, all Python processes share that permission. Most keynote-mcp tools use ordinary AppleScript (no accessibility permission needed) — only building animations requires that permission. For stricter isolation, you can build a standalone binary so that keynote-mcp has its own permission entry.
About the Skill The keynote-presentation skill (skills/keynote-presentation/) solves real problems found in production use:
- Font clipping bug: Large font sizes (>48pt) create extremely small text boxes, clipping text to 1-2 characters. The skill teaches Claude the workaround of resizing first, then editing.
- Theme pitfalls: Many themes (Gradient, Minimalist Dark) do not display a background on blank slides. The skill includes a tested compatibility table.
- Coordinate calculation: There is no text-align property. The skill provides per-character width estimation for manual centering.
- Shape fill limitation: Shape fill colors cannot be written via AppleScript. The skill documents a transparency workaround for dark theme containers.
- Dark theme color reference: Tested RGB values for white text, gray subtitles, green code comments, and blue section headings.
- Two-column layout: Proven coordinates for slides with code on the left/bullets on the right using add_shape containers.
- Design patterns: Landing-page-style slide templates (hero, statement, bullets, code demo, closing) with tested positions.
Project Structure Includes sections such as skill structure, project structure, and standalone binary.
Standalone Binary For security-conscious users who do not want to grant accessibility permission to the shared python binary, keynote-mcp can be built as a standalone executable with its own permission entry. Then use that binary in the MCP configuration. When accessibility permission is granted, it will appear as "keynote-mcp" instead of "Python". See CONTRIBUTING.md for details.
License MIT — see LICENSE.
Acknowledgments
- Model Context Protocol — a standardized tool protocol for AI
- Unsplash — free high-quality images
- AppleScript — macOS automation
- The original project was created by easychen