iwork-studio

<div align="center">

<!-- mcp-name: io.github.Arkanji/iwork-studio -->

<img src="https://raw.githubusercontent.com/Arkanji/iwork-studio/main/assets/banner.svg" alt="iWork Studio — read and edit Apple Numbers, Keynote and Pages with Python" width="100%">

[![CI](https://github.com/Arkanji/iwork-studio/actions/workflows/ci.yml/badge.svg)](https://github.com/Arkanji/iwork-studio/blob/main/.github/workflows/ci.yml)
[![Version](https://img.shields.io/pypi/v/iwork-studio?label=version&color=1a7f79)](https://pypi.org/project/iwork-studio/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Arkanji/iwork-studio/tree/main/LICENSE)
[![iWork](https://img.shields.io/badge/iWork-classic%20%2B%20Creator%20Studio-black?logo=apple&logoColor=white)](#what-it-can-do)
[![MCP server](https://img.shields.io/badge/MCP-64%20tools-8A2BE2)](#all-64-tools)
[![Arabic safe](https://img.shields.io/badge/Arabic%2FRTL-exact%20round--trips-informational)](#arabic--rtl)
[![Undo](https://img.shields.io/badge/every%20write-backed%20up%20%2B%20undoable-success)](#the-safety-model)

### Give your AI the keys to Apple iWork.

Create, edit, format, theme and export **Numbers**, **Keynote** and **Pages** files from Claude or any AI agent.<br>
Every write is backed up, checked and swapped in atomically, and any change can be undone with one call.

[**Install**](#install) · [What it can do](#what-it-can-do) · [Safety](#the-safety-model) · [All 64 tools](#all-64-tools) · [For AI agents](#for-ai-agents) · [Changelog](https://github.com/Arkanji/iwork-studio/blob/main/CHANGELOG.md)

<br>

<a href="https://arkanji.com/images/posts/iwork-studio-film-v3.mp4">
  <img src="https://raw.githubusercontent.com/Arkanji/iwork-studio/main/assets/iwork-studio-film.webp" alt="iWork Studio in action: an AI agent edits a Numbers cell and keeps its formula, updates every Keynote slide without touching the formatting, and writes an Arabic letter in Pages" width="100%">
</a>

<sub>▶ <a href="https://arkanji.com/images/posts/iwork-studio-film-v3.mp4"><b>Watch the film with sound</b></a> (46s) · <a href="https://arkanji.com/posts/iwork-studio-launch/">Read the launch story</a></sub>

</div>

---

## Install

| Your app | Do this |
|---|---|
| **Claude desktop app, one click** (Mac) | Download `iwork-studio-<version>.mcpb` from the [latest release](https://github.com/Arkanji/iwork-studio/releases/latest), double-click it, pick the folders it may use |
| **Claude desktop app** (Mac, from Terminal) | Paste in Terminal: `curl -LsSf https://raw.githubusercontent.com/Arkanji/iwork-studio/main/install.sh \| sh`, then quit Claude (Cmd-Q) and reopen |
| **Claude Code, as a plugin** (tools + skill) | `/plugin marketplace add Arkanji/iwork-studio`, then `/plugin install iwork-studio@iwork-studio` |
| **Claude Code, tools only** | `claude mcp add iwork-studio -- uvx --from git+https://github.com/Arkanji/iwork-studio iwork-studio-mcp` |
| **Cursor, VS Code, Codex, any MCP client** | `uvx --from git+https://github.com/Arkanji/iwork-studio iwork-studio-mcp config`, then paste the printed JSON into the client's MCP settings. Also listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.Arkanji/iwork-studio` |

That's it. The installer sets up [`uv`](https://docs.astral.sh/uv/) if needed, and uv brings its own Python.

- **Fence it** (recommended): `… | sh -s -- --roots ~/Documents ~/Desktop` limits it to those folders. Other clients: set `IWORK_STUDIO_ROOTS` (`:`-separated).
- **Load less** (optional): only work in Keynote? Set `IWORK_STUDIO_TOOLSETS=keynote,design` (any of `files`, `numbers`, `keynote`, `pages`, `design`; default all). Fewer tools keep the AI focused and its context small. The Claude Desktop extension has a *Toolsets* field; in Claude Code: `claude mcp add iwork-studio -e IWORK_STUDIO_TOOLSETS=keynote,design -- uvx --from git+https://github.com/Arkanji/iwork-studio iwork-studio-mcp`. Capabilities, read, find, undo and the kit list always load.
- **First run:** macOS asks once whether Claude may control Keynote / Pages / Numbers. Click **OK**. (Missed it? System Settings → Privacy & Security → Automation.)
- **Check it:** ask *"what can iwork-studio do on this Mac?"*.
- **Remove:** `uvx --from git+https://github.com/Arkanji/iwork-studio iwork-studio-mcp uninstall`

> **AI agent setting this up for someone?** Pick the row for their app, run it, then call `iwork_capabilities`. Rules for using the tools are in [`AGENTS.md`](https://github.com/Arkanji/iwork-studio/blob/main/AGENTS.md).

## Just ask, in English or Arabic

> *"Build a 6-slide pitch deck on programmable gift cards in the midnight kit, with speaker notes, and export it to PowerPoint."*
>
> *"Turn sales.numbers into a board deck: chart the quarters, a table of the top regions, in our Resal kit."*
>
> *"Take the fonts and colours from brand.key and save them as our Resal kit."*
>
> *"Review pitch.key and fix anything that overflows or is too small to read."*
>
> *"Make budget.numbers look professional with the banking kit — and show me a preview first."*
>
> *"Turn sales.csv into a Numbers file, make the header bold on a teal fill, show column B as SAR with two decimals, and add a total row."*
>
> *"In pitch.key, switch to the Gradient theme, make the title on slide 1 white at 60 pt, add a dissolve between every slide, and put logo.png on the last slide."*
>
> *"Add a bar chart of revenue by quarter for 2025 and 2026 to slide 4."*
>
> *"Duplicate slide 3, move the copy to the front and add presenter notes: ملاحظات المتحدث"*
>
> *"Fill the Name and Date fields in offer-letter.pages, then export it as a password-protected PDF."*
>
> *"In the invoice.pages table, set the quantity in B3 to 12 and make D9 the total of D2:D8."*
>
> *"Find my Keynote decks from this week and export each one to PowerPoint."*
>
> *"Undo the last change to budget.numbers."*

## What it can do

| | **Numbers** | **Keynote** | **Pages** |
|---|---|---|---|
| **Read** | Every sheet, table, cell, formula and format | Every slide's text, notes, layout, theme, styling and charts | Body text, placeholders and tables |
| **Create** | From data or CSV ⚡ · from a built-in template · from your own file | **A designed deck from an outline, with chart and table slides** (straight from a Numbers table) · from a built-in theme · from your own deck | From a built-in template · from your own file |
| **Edit content** | Cells ⚡ · formulas · recalculate · insert/delete rows and columns ⚡ · add tables and sheets ⚡ · sort | Find/replace across the deck ⚡ · slide titles and bullets · add, duplicate, delete, move, hide slides · presenter notes · images · charts · tables | Replace text everywhere · replace the body · fill placeholders · table cells (text, numbers, formulas) |
| **Design** | Design kits ⚡ · your brand kit ⚡ · fonts, colours, fill, alignment, wrap ⚡ · currency, %, dates, decimals ⚡ · borders ⚡ · widths and heights ⚡ · headers ⚡ · merges ⚡ | Design kits · your brand kit · theme · slide layout · text font, size and colour · styled tables · transitions | — |
| **Review** | | **Design review** of what Keynote draws: text off the slide or past its box, text Keynote had to shrink, overlaps, small text, crowded slides · any slide as an image | |
| **Export** | PDF · Excel · CSV | PDF · PowerPoint · images · movie | PDF · Word · EPUB · text · RTF |
| **Present** | | Start, stop, next, previous | |

⚡ = works anywhere, no app needed (pure Python). Everything else drives the real app on a Mac with a logged-in session, classic iWork or the Creator Studio apps.

**Every file type:** preview any change before it's made (`dry_run`), look up metadata, pull the preview thumbnail, find files with Spotlight, check that a word is visibly rendered, check the rendered font/size/colour, list backups and undo.

### What it won't do

On purpose, so it never breaks a file:

- **Files with charts** are refused by the tools that work without the app: their rewrite can silently break a chart's link to its data. The app-driven tools (Keynote slides, theming, transitions, images; Numbers formulas and sort) work on them and check every chart is still there.
- **Charts in Numbers and Pages** can't be created: Apple doesn't make them scriptable. Keynote charts can be added. To chart sorted data without touching a Numbers chart, sort into a new table (`numbers_sort` with `to_new_table`) and build a Keynote chart slide from it.
- **Pages** is limited to text and existing tables: replace, set body, placeholders and table cells. New tables can't be created (Pages 15 doesn't script it), and page-layout documents, like most letter templates, have no body text. There is no Pages file format parser anywhere, so it doesn't fake one.
- **Formulas and row shifts**: in a table that has formulas, rows and columns can only be appended without the app. Inserting in the middle would leave references pointing at the wrong cells.
- **Not scriptable by Apple**, so not offered: Numbers table styles, Keynote shape fill and text alignment, deleting a Keynote table, editing a theme's master slides. Page margins and page setup are planned.

## Designed, not just edited

Six **design kits** turn a plain deck or table into something you'd present: a font pair (Latin + Arabic, all bundled with macOS — nothing to install), a restrained palette checked for WCAG contrast, and a type scale.

| Kit | Feel |
|---|---|
| `executive` | Calm and corporate: slate neutrals, one blue accent |
| `banking` | Trust and weight: deep navy, restrained gold |
| `classic` | Formal reports and boards: serif headings, navy and amber |
| `teal` | Fresh and confident: deep teal |
| `analytics` | Data-forward: strong blue, amber highlights |
| `midnight` | Dark stage: near-black slides, white titles, mint accent |

Build with one (`keynote_build_deck(..., kit="midnight")`), restyle anything (`keynote_apply_design`, `numbers_apply_design`), or bring your brand as colours