Which integrations are available for this server?

Enables programmatic control and automation of Apple Keynote, allowing the creation, editing, and management of presentation files via AppleScript. Utilizes macOS system automation and UI scripting capabilities to interact with the Keynote application and handle presentation tasks. Provides integration with the Unsplash API to search for high-quality images and insert them directly into presentation slides.

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:

Zip the skills/keynote-presentation folder
Go to Settings > Capabilities > Skills
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 (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

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

keynote-mcp