Keynote Harvest MCP server

Keynote Harvest MCP

keynote-harvest-mcp is a local stdio MCP server for turning Keynote exports and PDFs into portable slide previews, extractable text, embedded-image assets, and a versioned manifest.

It contains only the harvest-first MCP boundary:

• Keynote app discovery.
• Native .key to PDF export on macOS.
• PDF-first harvest into previews, extractable text, assets, and a manifest.
• Display-safe manifest reads.
• Local harvest output listing.
• MCP resources for manifests, previews, extracted embedded-image assets, and extracted text. Source PDFs are denied by default and require the operator-only KEYNOTEHARVESTALLOWSOURCERESOURCES=1 capability.

It intentionally excludes composition/proposal tools, web-framework renderers, preview routes, OCR, vision, and LLM calls.

Requirements

• macOS or Linux (declared via the package os field; Windows is unsupported).
• Node.js 22 or newer (maintained LTS releases).
• Poppler commands pdfinfo, pdftoppm, and pdftotext for PDF harvests.
• Poppler pdfimages for embedded-image asset extraction, which is on by default. Without pdfimages the harvest still completes and records a manifest warning; pass extractImages: false (CLI: --no-extract-images) to skip extraction, or extractImages: true (CLI: --extract-images) to require pdfimages and fail when it is missing.
• macOS, Keynote, and Automation permission for native .key export only.

PDF harvesting can run without Keynote. OCR, vision, LLM calls, .key package parsing, and presenter-note extraction are intentionally absent.

Manifest Contract

New harvests use schemaVersion: "keynote-harvest-manifest-v1". The package owns three aligned representations of that contract:

• TypeScript types under src/types/.
• Runtime structural validation under src/schema/.
• A distributable Draft 2020-12 JSON Schema at schema/keynote-harvest-manifest-v1.schema.json.

The runtime validator requires the version by default. Its explicit allowLegacyVersion option exists only to inspect older private manifests created before schema versioning; newly generated manifests are always versioned.

Schema Evolution

Additive, optional fields may be introduced without changing keynote-harvest-manifest-v1. Any breaking contract change must mint keynote-harvest-manifest-v2 with a separate schema file, while the runtime validator retains support for reading v1. allowLegacyVersion remains limited to pre-versioned private manifests and is not a substitute for versioned schema migrations.

Install, Build, And Test

cd keynote-harvest-mcp
npm ci
npm run build
npm test

npm run test:clean-install copies the package to a temporary directory, runs npm ci, rebuilds it, and executes the package-owned tests in isolation from this checkout's installed dependencies.

npm run test:packed-runtime builds a local tarball, installs it into an empty consumer project, starts the installed binary, and verifies the packaged tool surface. Neither rehearsal publishes anything.

npm run test:pdf-runtime generates public-safe PDFs, exercises replacement and quota failures through local Poppler commands, validates path-safe v1 manifests, and removes all temporary output.

The built server and tools execute JavaScript from dist/; they do not execute source TypeScript at runtime.

Quickstart

The package is on npm. Point each stdio MCP host at npx -y keynote-harvest-mcp; the first run downloads it, later runs use the cache. GUI hosts may not inherit your shell's PATH, so give them the absolute npx executable (command -v npx). To run from a local checkout instead, see "Local build" at the end of this section.

Claude Code

claude mcp add keynote-harvest \
  -e KEYNOTE_HARVEST_WORKING_DIRECTORY=/path/to/your/working-directory \
  -e KEYNOTE_HARVEST_ROOT=.harvests \
  -e KEYNOTE_HARVEST_ALLOWED_INPUT_ROOTS=/path/to/your/decks \
  -- npx -y keynote-harvest-mcp

Shortened. The full README is on GitHub.