Keynote MCP Server

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

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+)

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