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 KEYNOTE_HARVEST_ALLOW_SOURCE_RESOURCES=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

Use --scope user when the server should be available outside the current project, and verify the registration with claude mcp get keynote-harvest.

Claude Desktop

Add this server to claude_desktop_config.json through Claude Desktop's developer settings, then fully quit and relaunch the application:

{
  "mcpServers": {
    "keynote-harvest": {
      "command": "/absolute/path/to/npx",
      "args": ["-y", "keynote-harvest-mcp"],
      "env": {
        "KEYNOTE_HARVEST_WORKING_DIRECTORY": "/path/to/your/working-directory",
        "KEYNOTE_HARVEST_ROOT": ".harvests",
        "KEYNOTE_HARVEST_ALLOWED_INPUT_ROOTS": "/path/to/your/decks"
      }
    }
  }
}

Claude Desktop stops every tool call at roughly four minutes, so harvest long decks with runInBackground: true and poll get_harvest_manifest.

Cursor

Create .cursor/mcp.json in a project, or ~/.cursor/mcp.json for a global configuration:

{
  "mcpServers": {
    "keynote-harvest": {
      "command": "/absolute/path/to/npx",
      "args": ["-y", "keynote-harvest-mcp"],
      "env": {
        "KEYNOTE_HARVEST_WORKING_DIRECTORY": "/path/to/your/working-directory",
        "KEYNOTE_HARVEST_ROOT": ".harvests",
        "KEYNOTE_HARVEST_ALLOWED_INPUT_ROOTS": "/path/to/your/decks"
      }
    }
  }
}

Codex CLI

Register the server with codex mcp add (stdio transport):

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

Two Codex behaviors to know: the harvest and export tools are annotated destructiveHint: true, so Codex asks for approval before running them — non-interactive codex exec sessions with approval: never cancel them ("user cancelled MCP tool call") unless approvals are bypassed. And Codex exposes MCP tools only, not resources; read results through get_harvest_manifest and the harvest directory. Codex's default per-call limit is 300 s; raise it for long decks with mcp_servers.keynote-harvest.tool_timeout_sec, or use runInBackground: true and poll.

Local build

To run from a checkout instead of npm:

cd /absolute/path/to/keynote-harvest-mcp
npm ci
npm run build

Then use /absolute/path/to/node /absolute/path/to/keynote-harvest-mcp/dist/index.js as the command in any of the configurations above, keeping the same env.

Not supported: ChatGPT

ChatGPT connects only to remote (HTTP) MCP servers. This package is a local stdio server by design — no network, and native export needs Keynote on the same Mac — so ChatGPT is out of scope for v0.1.

The package resolves relative paths from the caller's current directory. Set KEYNOTE_HARVEST_WORKING_DIRECTORY when an MCP host should use a different working directory. Local source files must be inside the working directory, harvest root, or a path-delimited KEYNOTE_HARVEST_ALLOWED_INPUT_ROOTS entry. The server returns harvest-relative artifact paths and resource URIs rather than absolute paths.

Native export returns exportedPdfHarvestPath, which can be passed to harvest_keynote_pdf as harvestPdfPath. get_harvest_manifest accepts a harvest slug, not an arbitrary manifest file path.

Tool responses are summaries, not the manifest. Every response carries a responseKind: harvest-summary and export-summary from the write tools, manifest-summary from get_harvest_manifest (its source block is a flattened projection — sourceId, sourceKind, sourceDisplayName, harvestTool — of the manifest's source), and job-record / job-status for background jobs. The manifest itself, with its schema-defined field names, is the keynote-harvest://<slug>/keynote-harvest-manifest.json resource.

Keynote app selection trusts only bundles that carry an allowlisted identifier and an Apple first-party code signature — the codesign leaf authority must be "Apple Mac OS Application Signing" or "Software Signing"; Developer ID apps chain to Apple Root CA too, so the root alone proves nothing, and a bundle identifier alone is a claim any app can make. Set KEYNOTE_HARVEST_ALLOW_UNSIGNED_KEYNOTE=1 only for deliberately unsigned builds.