keynote-mcp 1.0.0

An MCP server for controlling Apple Keynote presentations via AppleScript

Keynote MCP

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

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, titles, subtitles, bullet lists, numbered lists, code blocks, quotes, images, edit, delete, move, resize elements, speaker notes
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.
• 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

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