Keynote Server

A Model Context Protocol (MCP) server that provides full programmatic control over Apple Keynote through AppleScript and JXA (JavaScript for Automation). Designed for use with Claude Desktop and any MCP-compatible client, this server lets you create, edit, present, and export Keynote presentations entirely through natural language.

Prerequisites

• macOS (any recent version with Keynote installed)
• Apple Keynote (free from the Mac App Store)
• Node.js 18+ (check with node --version)
• Accessibility permissions -- your terminal or IDE must be allowed to control Keynote via System Settings > Privacy & Security > Accessibility

Installation

git clone https://github.com/superdwayne/keynoteMP.git keynote-mcp-server
cd keynote-mcp-server
npm install
npm run build

Verify the build succeeds and types pass:

npx tsc --noEmit

Claude Desktop Configuration

Add the following entry to your claude_desktop_config.json (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "keynote": {
      "command": "node",
      "args": ["/absolute/path/to/keynote-mcp-server/dist/index.js"]
    }
  }
}

Replace /absolute/path/to/keynote-mcp-server with the actual path on your machine. Restart Claude Desktop after saving the configuration.

Tool Reference

The server registers 70 tools across 13 modules. All slide indices are 1-based.

Design Engine (8 tools)

The Design Engine automates professional slide composition with a brand-aware system including 23+ layouts, typography scaling, color harmonies, and presentation templates.

Tool	Parameters	Description
design_slide	slideIndex, title?, subtitle?, body?, bodyItems?, quote?, imagePaths?, stats?, layoutName?, primaryColor?, style?, variationSeed?, addAccents?	Composes a complete slide with automatic layout, typography, and color
design_deck	slides[], primaryColor?, style?, addAccents?	Composes multiple slides with consistent branding and layout variety
set_brand	primaryColor?, secondaryColor?, accentColor?, backgroundColor?, fontPrimary?, fontSecondary?, style?	Sets brand configuration for subsequent design operations
get_brand	--	Extracts brand configuration from the active Keynote theme
list_layouts	category?	Lists all available slide layouts with descriptions and element details
list_templates	--	Lists all presentation templates with slide counts
get_template	templateName	Gets full structure of a template with content hints
design_from_template	templateName, slides?, primaryColor?, style?, startSlideIndex?	Creates a full presentation from a template

Available layouts: title-center, title-left, title-bold, section-break, section-gradient, content-left, content-right-image, content-left-image, two-column, three-column, full-image, image-grid, quote, statistic, comparison, closing-cta, closing-thankyou, blank-canvas, timeline, before-after, team-grid, pricing-table, roadmap

Available templates: pitch-deck (10 slides), status-update (5 slides), workshop (8 slides), product-launch (7 slides)

Brand styles: minimal, bold, elegant, playful, corporate

Presentation Management (6 tools)

Tool	Parameters	Description
create_presentation	themeName? (string)	Creates a new blank Keynote presentation, optionally with a named theme
open_presentation	filePath (string)	Opens an existing .key file by absolute path
save_presentation	filePath? (string)	Saves the frontmost presentation; provide a path for save-as
close_presentation	saving? (boolean, default: true)	Closes the frontmost presentation
list_presentations	--	Lists all open presentations with names and file paths
get_presentation_info	name? (string)	Returns slide count, theme, dimensions, and path for a presentation

Slide Management (7 tools)

Tool	Parameters	Description
add_slide	position? (int), masterSlideName? (string)	Adds a new slide at a given position with an optional layout
delete_slide	slideIndex (int)	Removes a slide by index
duplicate_slide	slideIndex (int)	Duplicates a slide at the given index
move_slide	fromIndex (int), toIndex (int)	Moves a slide from one position to another
get_slide_count	--	Returns total number of slides
list_slides	--	Returns all slides with index, title, and layout name
get_slide_layout_names	--	Lists available master slide / layout names for the current theme

Text Content (7 tools)

Tool	Parameters	Description
set_slide_title	slideIndex (int), text (string)	Sets the title text of a slide
set_slide_body	slideIndex (int), text (string)	Sets the body text of a slide
add_text_item	slideIndex (int), text (string), x, y, width, height (numbers), role? (display/heading/subheading/body/caption/quote/overline/bodySmall), autoPosition? (boolean)	Adds a text box with optional brand-aware typography via role
update_text_item	slideIndex (int), itemIndex (int), text (string)	Updates text content of an existing text item
delete_text_item	slideIndex (int), itemIndex (int)	Removes a text item from a slide
list_text_items	slideIndex (int)	Lists all text items on a slide with content, position, and size
format_text	slideIndex (int), itemIndex (int), fontName?, fontSize?, bold?, italic?, color? (hex), alignment? (left/center/right)	Applies formatting to a text item

Images & Media (5 tools)

Tool	Parameters	Description
add_image	slideIndex (int), filePath (string), x?, y?, width?, height? (numbers), role? (hero-image/thumbnail/background-image/icon/inline/avatar)	Adds an image with optional role-based sizing
replace_image	slideIndex (int), imageIndex (int), filePath (string)	Replaces an existing image with a new file
delete_image	slideIndex (int), imageIndex (int)	Removes an image from a slide
list_images	slideIndex (int)	Lists all images on a slide with positions and file names
set_image_position	slideIndex (int), imageIndex (int), x?, y?, width?, height? (numbers)	Repositions or resizes an existing image

Presenter Notes (3 tools)

Tool	Parameters	Description
set_presenter_notes	slideIndex (int), notes (string)	Sets presenter notes for a slide
get_presenter_notes	slideIndex (int)	Retrieves presenter notes for a slide
get_all_presenter_notes	--	Returns all slides' presenter notes as an array

Themes & Styling (6 tools)

Tool	Parameters	Description
list_themes	--	Lists available Keynote themes (queries Keynote or falls back to a built-in list)
apply_theme	themeName (string)	Applies a theme to the frontmost presentation
set_slide_background_color	slideIndex (int), color (hex string)	Sets a solid background color on a slide
set_slide_background_image	slideIndex (int), filePath (string)	Sets an image as the slide background
get_slide_master	slideIndex (int)	Returns the master slide / layout name for a slide
change_slide_master	slideIndex (int), masterName (string)	Changes a slide's master layout

Transitions & Animations (6 tools)

Tool	Parameters	Description
set_slide_transition	slideIndex (int), effect (string), duration? (number, default: 1.0)	Sets a transition effect on a slide
get_slide_transition	slideIndex (int)	Returns current transition settings for a slide
list_transition_types	--	Lists all 33 available transition effect names
add_build_animation	slideIndex (int), itemIndex (int), type (appear/dissolve/scale/move_in/fly_in/fade_and_move), buildType (in/out), duration? (number)	Adds a build-in or build-out animation to an item
remove_build_animation	slideIndex (int), itemIndex (int), buildType (in/out)	Removes an animation from an item
list_build_animations	slideIndex (int)	Lists all build animations for every item on a slide

Tables & Charts (6 tools)

Tool	Parameters	Description
add_table	slideIndex (int), rows (int), columns (int), x?, y?, width?, height? (numbers)	Adds a table to a slide
set_table_cell	slideIndex (int), tableIndex (int), row (int), column (int), value (string)	Sets the value of a specific table cell
set_table_data	slideIndex (int), tableIndex (int), data (string[][])	Bulk-sets table data from a 2D array
get_table_data	slideIndex (int), tableIndex (int)	Reads all data from a table as a 2D array
delete_table	slideIndex (int), tableIndex (int)	Removes a table from a slide
add_chart	slideIndex (int), chartType (bar/line/pie/area), x?, y?, width?, height?, data? (series array)	Adds a chart to a slide (may fall back to a data table due to AppleScript limitations)

Live Slideshow Control (6 tools)

Tool	Parameters	Description
start_slideshow	fromSlide? (int)	Starts the slideshow from the beginning or a specific slide
stop_slideshow	--	Stops the currently running slideshow
next_slide	--	Advances to the next slide or build
previous_slide	--	Goes back to the previous slide or build
go_to_slide	slideIndex (int)	Jumps to a specific slide during the slideshow
get_slideshow_status	--	Returns whether a slideshow is playing and the current slide number

Export (4 tools)

Tool	Parameters	Description
export_to_pdf	filePath (string)	Exports the presentation as a PDF
export_to_images	directoryPath (string), format? (PNG/JPEG)	Exports all slides as individual image files to a directory
export_to_pptx	filePath (string)	Exports as Microsoft PowerPoint (.pptx)
export_slide_to_image	slideIndex (int), filePath (string), format? (PNG/JPEG)	Exports a single slide as an image file

Content Extraction (2 tools)

Tool	Parameters	Description
get_slide_content	slideIndex (int)	Returns all content on a slide: title, body, text items, images, shapes, tables, and notes
get_full_presentation_content	--	Returns a structured summary of the entire presentation with per-slide details

Shapes & Drawing (4 tools)

Tool	Parameters	Description
add_shape	slideIndex (int), shapeType (rectangle/circle/triangle/arrow_right/arrow_left/star/diamond/line), x, y, width, height (numbers), fillColor? (hex), role? (accent-shape/divider/background-shape/highlight/background-panel)	Adds a shape with optional brand-aware color via role
delete_shape	slideIndex (int), shapeIndex (int)	Removes a shape from a slide
list_shapes	slideIndex (int)	Lists all shapes on a slide with position and size
update_shape	slideIndex (int), shapeIndex (int), x?, y?, width?, height?, fillColor?, borderColor?, borderWidth?	Modifies a shape's position, size, or styling

Usage Examples

Design a pitch deck from a template

"Create a pitch deck for my startup using the pitch-deck template with our brand colors #2563EB and an elegant style."

Claude will call set_brand, then design_from_template with "pitch-deck", generating all 10 slides with coordinated layouts, typography, and transitions.

Design a single slide with brand-aware styling

"Design slide 3 with the title 'Market Opportunity', body text about the TAM, and use the statistic layout."

Claude will call design_slide with the content and layout name, automatically applying brand colors and typography.

Create a presentation from scratch

"Create a new Keynote presentation with the Gradient theme, add 5 slides, and set titles for each one."

Claude will call create_presentation, then add_slide five times, and set_slide_title for each slide.

Build a data-driven slide

"On slide 3, add a table with quarterly revenue data: Q1: $1.2M, Q2: $1.5M, Q3: $1.8M, Q4: $2.1M."

Claude will use add_table, then set_table_data to populate the cells.

Export for sharing

"Export my presentation as a PDF to the Desktop and also save each slide as a PNG image."

Claude will call export_to_pdf and export_to_images with the appropriate paths.

Add brand-aware text and shapes

"Add a heading with role 'display' on slide 1 that says 'Welcome'."

Claude will call add_text_item with role: "display", which automatically applies brand-aware font, size, and color with WCAG-compliant contrast.

Architecture

keynote-mcp-server/
  src/
    index.ts              # Entry point -- creates MCP server, registers all tool modules
    applescript.ts        # AppleScript/JXA execution bridge (runAppleScript, runJXA)
    tools/
      presentation.ts     # create, open, save, close, list, info
      slides.ts           # add, delete, duplicate, move, count, list, layouts
      text.ts             # title, body, text items, formatting (brand-aware via role)
      images.ts           # add, replace, delete, list, reposition (role-based sizing)
      notes.ts            # set, get, get-all presenter notes
      theme.ts            # themes, backgrounds, master slides
      transitions.ts      # slide transitions, build animations
      tables-charts.ts    # tables (CRUD + bulk data), charts
      slideshow.ts        # start, stop, next, previous, go-to, status
      export.ts           # PDF, images, PowerPoint, single-slide export
      content.ts          # read slide content, full presentation summary
      shapes.ts           # add, delete, list, update shapes (brand-aware via role)
      design.ts           # design_slide, design_deck, set_brand, get_brand, list_layouts,
                          #   list_templates, get_template, design_from_template
    design/
      tokens.ts           # Design tokens (spacing, margins, canvas sizes)
      color.ts            # Color math, harmonies, WCAG contrast
      typography.ts       # Type scale system (8 roles, modular scale)
      grid.ts             # 12-column, 8-row grid system
      layouts.ts          # Layout definition schema
      layout-library.ts   # 23+ pre-built slide layouts
      brand.ts            # Brand configuration, theme extraction
      brand-state.ts      # Shared brand state across all tool modules
      balance.ts          # Visual balance and whitespace utilities
      accents.ts          # Decorative accent generation
      variations.ts       # Layout variation engine (mirror, shift, toggle)
      composer.ts         # Slide/deck composition orchestration
      templates.ts        # Presentation templates (pitch-deck, status-update, etc.)
      progress.ts         # Progress indicators for multi-slide decks
  dist/                   # Compiled JavaScript output (generated by `npm run build`)
  package.json
  tsconfig.json

The server uses stdio transport (standard for local MCP servers). Each tool module exports a register*Tools(server) function that registers tools with the MCP server instance. All Keynote automation is performed by shelling out to osascript via child_process.execFile, using either AppleScript or JXA depending on the operation.

Troubleshooting

"AppleScript error: Not authorized to send Apple events"

Your terminal or IDE needs Accessibility permissions. Go to System Settings > Privacy & Security > Accessibility and add your terminal application (Terminal.app, iTerm2, VS Code, etc.).

You may also need to grant permissions under Privacy & Security > Automation to allow your terminal to control Keynote.

"Keynote got an error: Can't get document 1"

No Keynote presentation is currently open. Use create_presentation or open_presentation first.

Build errors

Make sure you have Node.js 18+ installed and run npm install before npm run build. The project requires TypeScript and the MCP SDK as dependencies.

Keynote must be installed

This server controls Keynote.app via AppleScript. It will not work without Keynote installed. Keynote is free from the Mac App Store.

Chart creation limitations

Direct chart creation via AppleScript is limited in some Keynote versions. The add_chart tool will attempt to create a chart directly but may fall back to creating a data table with your values. You can then manually convert that table to a chart in Keynote.

Timeout errors

Each AppleScript command has a 30-second timeout. Operations on very large presentations or complex exports may occasionally time out. If this happens, try the operation again or work with fewer slides at a time.

License

MIT