keynote-mcp

Local macOS MCP server that reads, edits, and exports Apple Keynote presentations via JXA (JavaScript for Automation). Enables Claude to visually analyze slides, apply design changes, and iterate on presentations directly — without any third-party tools.

Requirements

• macOS with Apple Keynote installed
• Node.js 20+
• Keynote must be running with at least one document open

Installation

git clone https://github.com/tszaks/keynote-mcp
cd keynote-mcp
npm install && npm run build

Add to ~/.mcp.json:

{
  "mcpServers": {
    "keynote-mcp": {
      "type": "stdio",
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/keynote-mcp/dist/index.js"]
    }
  }
}

Restart Claude Code. Tools appear as mcp__keynote-mcp__keynote_*.

---

Tools Reference

All tools accept doc_index (0-based, defaults to 0 = frontmost document). Elements are addressed by slide_index (0-based) + element_type (textItem, imageItem, shapeItem) + element_index (0-based within that collection). Colors are [r, g, b] with values 0–255. Slide coordinates are in points; standard Keynote slide is 1920×1080 pts.

Discovery

keynote_list_presentations

List all open Keynote documents.

Input: {}
Output: [{ index, name, slideCount, modified, filePath }]

keynote_get_presentation_info

Get slide count and available master slide names. Call this first before redesigning — you need master names to call keynote_apply_master.

Input: { doc_index? }
Output: { name, slideCount, masterSlides: string[], filePath, modified }

keynote_get_slide

Get the full element tree for one slide: all text boxes, images, and shapes with position, size, font, font size, and color.

Input: { doc_index?, slide_index }
Output: {
  slideIndex, masterSlide, skipped, elementCount,
  elements: [{
    type: "textItem" | "imageItem" | "shapeItem",
    index,
    text?,         // textItem only
    font?,         // textItem only
    fontSize?,     // textItem only
    color?,        // textItem only — [r,g,b] 0-255
    fillColor?,    // shapeItem only — [r,g,b] 0-255
    fileName?,     // imageItem only
    position: { x, y },
    size: { w, h }
  }]
}

Export (Visual Analysis)

keynote_export_slide_image

Export a single slide as PNG. Returns the file path — use the Read tool on that path to see the slide visually.

Input: { doc_index?, slide_index }
Output: { filePath, slideIndex, exportDir }

keynote_export_all_slides

Export all slides as PNG to ~/Library/Caches/keynote-mcp/<doc>/. Returns array of file paths.

Input: { doc_index? }
Output: { exportDir, slideCount, files: string[] }

keynote_get_design_snapshot

Best starting point for redesign. One call that exports all slides as PNG AND returns the full element tree for every slide.

Input: { doc_index? }
Output: {
  presentationName, slideCount, exportDir,
  slideImages: string[],   // PNG file paths — Read these for visual analysis
  slides: SlideData[]      // full element trees
}

Text & Font

keynote_set_text

Replace the text content of a text element. Preserves existing font styling.

Input: { doc_index?, slide_index, element_type: "textItem", element_index, text }

keynote_set_font

Set font family, size, and/or color on a text element. Omit any field to leave it unchanged.

Input: {
  doc_index?, slide_index,
  element_type: "textItem", element_index,
  font_name?,   // e.g. "SF Pro Display", "Helvetica Neue", "Didot"
  font_size?,   // points
  color?        // [r,g,b] 0-255
}

Layout

keynote_set_element_position

Move an element. x = distance from left edge, y = distance from top edge, both in points.

Input: { doc_index?, slide_index, element_type, element_index, x, y }

keynote_set_element_size

Resize an element.

Input: { doc_index?, slide_index, element_type, element_index, width, height }

Color & Fill

keynote_set_slide_background

Set slide background to a solid color. May fail if the slide's master has a locked background — apply a blank master first with keynote_apply_master.

Input: { doc_index?, slide_index, color: [r,g,b] }

keynote_set_element_fill_color

Set the fill color of a shape element.

Input: { doc_index?, slide_index, element_type: "shapeItem", element_index, color: [r,g,b] }

Add & Delete Elements

keynote_add_text_box

Add a new text box to a slide.

Input: { doc_index?, slide_index, text?, x?, y?, width?, height? }
Output: { added, slideIndex, newElementIndex }

keynote_add_shape

Add a rectangle or oval shape, with optional fill color.

Input: { doc_index?, slide_index, x?, y?, width?, height?, fill_color?: [r,g,b] }
Output: { added, slideIndex, newElementIndex }

keynote_delete_element

Remove an element from a slide. Keynote undo (Cmd+Z) still works in the app.

Input: { doc_index?, slide_index, element_type, element_index }

Slides

keynote_apply_master

Apply a master slide to one slide or all slides. Get valid master names from keynote_get_presentation_info.

Input: { doc_index?, master_name, slide_index? }
// Omit slide_index to apply to all slides

keynote_add_slide

Append a new blank slide at the end.

Input: { doc_index? }
Output: { added, newSlideIndex, slideCount }

keynote_delete_slide

Delete a slide.

Input: { doc_index?, slide_index }

keynote_duplicate_slide

Duplicate a slide. The copy is inserted immediately after the original.

Input: { doc_index?, slide_index }

---

Workflow Patterns

Visual Design Review

1. keynote_get_design_snapshot          → get all slide images + element trees
2. Read(slideImages[0])                 → see slide 0 visually
3. Read(slideImages[1])                 → see slide 1 visually
   ...
4. Identify issues: inconsistent fonts, low contrast, crowded layouts
5. Apply fixes with set_font / set_element_position / set_slide_background
6. keynote_export_slide_image           → verify the result visually

Enforce Typography Consistency

1. keynote_get_slide for each slide     → collect all font names and sizes
2. Identify the dominant font family
3. keynote_set_font on outliers to match

Redesign a Single Slide

1. keynote_export_slide_image           → see current state
2. keynote_get_slide                    → get element positions and sizes
3. Apply repositions, resizes, font changes
4. keynote_export_slide_image           → verify result

---

Known Limitations

• Export requires a saved file — if filePath is empty in list_presentations, save the document first (Cmd+S). Export will fail on unsaved presentations.
• Element positions return 0,0 for some Keynote layouts — this is a JXA limitation with certain master/layout combinations. Text content and font data are unaffected.
• Background color changes may be blocked by master slide locks. Use keynote_apply_master with a blank master first.
• No animation access — JXA does not expose Keynote transition or build animation properties.
• Image content is not readable — imageItem elements return file name and dimensions only, not pixel data.

---

Architecture

TypeScript MCP server using the @modelcontextprotocol/sdk. All Keynote interaction goes through JXA (JavaScript for Automation) via osascript -l JavaScript. Operations and payloads are passed as environment variables; results return as a JSON envelope { ok: boolean, result? | error? } on stdout.

Follows the same pattern as reminders-mcp, safari-mcp, and other local macOS MCP servers in the same ecosystem.