ByAxe/keynote-mcp

License: MIT Python 3.10+ PyPI macOS

An MCP server that gives AI full control over Apple Keynote through AppleScript automation. Create, edit, and export presentations — all via natural language.

Ships with a Claude Skill that encodes layout rules, font workarounds, and design patterns so presentations come out right on the first try.

Quick Start

Prerequisites

• macOS 10.14+
• Keynote application installed
• Python 3.10+

Option A: Install from PyPI

pip install keynote-mcp

Or run directly with uvx (no install needed):

uvx keynote-mcp

Option B: Install from source

git clone https://github.com/ByAxe/keynote-mcp.git
cd keynote-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .

Register the MCP server

Claude Code (PyPI install / uvx):

claude mcp add keynote-mcp keynote-mcp

Claude Code (from source):

claude mcp add keynote-mcp "bash -c cd $(pwd) && .venv/bin/python -m keynote_mcp"

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "keynote-mcp": {
      "command": "keynote-mcp",
      "env": {
        "UNSPLASH_KEY": "your_key_here"
      }
    }
  }
}

Or if using uvx:

{
  "mcpServers": {
    "keynote-mcp": {
      "command": "uvx",
      "args": ["keynote-mcp"],
      "env": {
        "UNSPLASH_KEY": "your_key_here"
      }
    }
  }
}

Other MCP clients:

• Command: keynote-mcp (if installed via pip) or uvx keynote-mcp
• Transport: stdio

3. Install the Skill (recommended)

The keynote-presentation skill teaches Claude how to use the MCP tools correctly — handling font clipping bugs, theme pitfalls, coordinate math, and design patterns.

Claude Code — copy the skill folder to your skills directory:

cp -r skills/keynote-presentation ~/.claude/skills/keynote-presentation

Claude.ai:

1. Zip the skills/keynote-presentation folder
2. Go to Settings > Capabilities > Skills
3. Click "Upload skill" and select the zip

4. 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 granted per-binary, not per-project. When you grant Accessibility access to python, all Python processes share that permission. Most keynote-mcp tools use plain AppleScript (no Accessibility needed) — only build animations require it. For stricter isolation, you can build a standalone binary (see Standalone Binary below) so keynote-mcp gets its own permission entry.

5. Use it

"Create a presentation about our Q1 results with 6 slides"
"Add a slide with a code example showing the API"
"Export the presentation as PDF"

Available Tools (30+)

Category	Tools
Presentation	create, open, save, close, list, themes, resolution, slide size
Slides	add, delete, duplicate, move, select, layouts, slide info
Content	text boxes (with font/color control), titles, subtitles, bullet lists, numbered lists, code blocks (with color), quotes, images, shapes (with opacity), edit, delete, move, resize elements, set element opacity, clear slide, speaker notes, build-in animations (add/remove via UI scripting)
Export	screenshot slides, export PDF
Unsplash	search images, add to slides, random images (requires UNSPLASH_KEY)

Unsplash Integration (optional)

cp env.example .env
# Add your key from https://unsplash.com/developers
# UNSPLASH_KEY=your_access_key

About the Skill

The keynote-presentation skill (skills/keynote-presentation/) solves real problems discovered through production use:

• Font clipping bug: Large font sizes (>48pt) create tiny text boxes that clip text to 1-2 characters. The skill teaches Claude the resize-then-edit workaround.
• Theme pitfalls: Many themes (Gradient, Minimalist Dark) don't show backgrounds on Blank slides. The skill includes a tested compatibility table.
• Coordinate math: No text-align property exists. The skill provides per-character width estimates for manual centering.
• Shape fill limitation: Shape fill color is NOT writable via AppleScript. The skill documents the opacity workaround for dark-theme containers.
• Dark theme color reference: Tested RGB values for white text, gray subtitles, green code comments, and blue section headers.
• Two-column layouts: Proven coordinates for code-left/bullets-right slides using add_shape containers.
• Design patterns: Landing-page-style slide templates (hero, statement, bullets, code demo, closing) with tested positions.

Skill structure

skills/keynote-presentation/
    SKILL.md                              # Main skill file with YAML frontmatter
    references/
        theme-reference.md                # Theme compatibility table
        coordinate-reference.md           # Layout math and centering formulas

Project Structure

src/
  keynote_mcp/
    __init__.py            # Package version
    __main__.py            # python -m keynote_mcp entry point
    server.py              # MCP server — routes tool calls via stdio
    tools/
      presentation.py      # Presentation lifecycle tools
      slide.py             # Slide management tools
      content.py           # Content creation and editing tools
      export.py            # Screenshot and PDF export tools
      unsplash.py          # Unsplash image integration
    utils/
      applescript_runner.py # Executes AppleScript via osascript
      error_handler.py     # Exception hierarchy and validation
    applescript/           # AppleScript source files
skills/                    # Claude Skills for this MCP
tests/                     # Test scaffolding

Standalone Binary

For security-conscious users who don't want to grant Accessibility permissions to the shared python binary, you can build keynote-mcp as a standalone executable with its own permission entry:

# Install pyinstaller
pip install pyinstaller

# Build standalone binary (~31MB)
pyinstaller --onefile --name keynote-mcp src/keynote_mcp/__main__.py

# Code-sign so macOS tracks it as its own app
codesign -s - -f dist/keynote-mcp

Then use the binary in your MCP config:

{
  "mcpServers": {
    "keynote-mcp": {
      "command": "/absolute/path/to/dist/keynote-mcp"
    }
  }
}

When you grant Accessibility permission, it will appear as "keynote-mcp" instead of "Python".

Contributing

See CONTRIBUTING.md for details.

License

MIT — see LICENSE.

Acknowledgments

• Model Context Protocol — standardized tool protocol for AI
• Unsplash — free high-quality images
• AppleScript — macOS automation
• Original project by easychen