# 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

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

Add to `~/.mcp.json`:

```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](https://github.com/tszaks/reminders-mcp), [safari-mcp](https://github.com/tszaks/safari-mcp), and other local macOS MCP servers in the same ecosystem.