Apple Numbers MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to read, write, search, and modify Apple Numbers (.numbers) spreadsheet files. Backed by the numbers-parser Python library.

<p align="center"> <img src="https://raw.githubusercontent.com/sweetrb/apple-numbers-mcp/main/codex/assets/screenshot.png" alt="Apple Numbers MCP — read, write, search, and format spreadsheets from Codex, Claude, and other AI assistants" width="680"> </p>

What is This?

This server acts as a bridge between AI assistants and Apple Numbers spreadsheets. Once configured, you can ask Claude (or any MCP-compatible AI) to:

• "What's in this spreadsheet?" — inspect sheets, tables, dimensions
• "Find every row where the customer is Acme Corp"
• "Export the Q3 Results table to CSV"
• "Set cell B5 to =SUM(B2:B4)"
• "Append these three rows to the Inventory table"
• "Bold and center the header row"
• "Import this CSV into a new spreadsheet"

The AI assistant communicates with this server, which uses numbers-parser to read and write .numbers files directly (no Numbers.app required for most operations). All data stays local on your machine.

Quick Start

Using Claude Code (Easiest)

If you're using Claude Code (in Terminal or VS Code), just ask Claude to install it:

Install the sweetrb/apple-numbers-mcp MCP server so you can help me work with my Numbers spreadsheets

Claude will handle the installation and configuration automatically. After install, you'll need to install numbers-parser (Python) — see Requirements below.

Or register it yourself in one deterministic line (no clone needed):

claude mcp add apple-numbers -s user -- npx -y apple-numbers-mcp

Using the Plugin Marketplace

Install as a Claude Code plugin for automatic configuration and enhanced AI behavior:

/plugin marketplace add sweetrb/apple-numbers-mcp
/plugin install apple-numbers

This method also installs a skill that teaches Claude when and how to use Apple Numbers effectively.

The plugin runs straight from its marketplace clone under ~/.claude/plugins/ (the clone lives at ~/.claude/plugins/marketplaces/apple-numbers-mcp/). On the first tool call the server auto-bootstraps a project-local Python venv inside that directory with numbers-parser — a one-time setup that takes about a minute and requires Python >= 3.11 on PATH (stock macOS ships 3.9 — brew install python@3.12 first). To pre-warm it instead of waiting on the first call, run scripts/setup.sh inside that install directory.

Using the Codex Marketplace

Install the same public marketplace in Codex:

codex plugin marketplace add sweetrb/apple-numbers-mcp
codex plugin add apple-numbers@apple-numbers-mcp

The Codex package registers the apple-numbers MCP server through npx -y apple-numbers-mcp — the same published-package invocation documented for Claude Desktop below — and bundles the Apple Numbers skill guidance. As with every install path, the numbers-parser Python sidecar must be available (pip3 install numbers-parser); see Requirements.

Other Hosts (Hermes, Antigravity)

Two more hosts can run the same apple-numbers MCP server (npx -y apple-numbers-mcp). All paths still need the numbers-parser Python sidecar available; see Requirements.

• Hermes Agent (NousResearch) — Hermes has no plugin/marketplace drop-in, so there is nothing in this repo to install from. Register the server with the CLI:

  hermes mcp add apple-numbers --command npx --args -y apple-numbers-mcp
  

  Or add it to ~/.hermes/config.yaml by hand:

  mcp_servers:
    apple-numbers:
      command: npx
      args: ["-y", "apple-numbers-mcp"]
  

  Restart your Hermes session afterward so the tools load.

• Antigravity (Google) — add the server entry from .antigravity-plugin/mcp_config.json to ~/.gemini/config/mcp_config.json (or via Antigravity's MCP settings).

Manual Installation

1. Install the server (from the npm registry):

npm install -g apple-numbers-mcp

2. Install numbers-parser (the Python library this server depends on):

pip3 install numbers-parser

Or, if you cloned the repo, run pnpm run setup to create a project-local Python venv with numbers-parser pre-installed.

3. Add to Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple-numbers": {
      "command": "npx",
      "args": ["apple-numbers-mcp"]
    }
  }
}

4. Restart Claude Desktop and start using natural language:

"What sheets are in ~/Documents/budget.numbers?"

Running from a clone in Claude Code (project-scope .mcp.json)

This repo ships a .mcp.json at its root so that, when you run claude from inside a clone, the server is registered automatically as a project-scope server — no manual config needed. Before launching, run both:

pnpm run build    # compile TypeScript to build/
pnpm run setup    # create the ./venv the Python sidecar needs

pnpm run setup is required because this is a Python-sidecar server: it shells out to ./venv/bin/python3 running numbers-parser. Without the venv, the server starts but every tool call fails. Then launch Claude Code from the repo directory and approve the server when prompted.

The entrypoint is written as:

"args": ["${CLAUDE_PROJECT_DIR:-.}/build/index.js"]

CLAUDE_PROJECT_DIR is the variable Claude Code injects into a project/user-scoped server's environment, and it resolves to the repo root. You must launch claude from inside the repo for this to work — the bare . fallback is only a last resort and is not reliable, because it resolves against the launching process's working directory, not the repo.

Why not ${CLAUDE_PLUGIN_ROOT}? CLAUDE_PLUGIN_ROOT is set only for marketplace plugin installs, never for a project-scope clone, so it can't drive the clone workflow. Conversely, a plugin install can't use CLAUDE_PROJECT_DIR (in a plugin, that points at the user's project, not the plugin's own directory). Claude Code does not support nested defaults like ${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-.}}, so a single entrypoint string cannot serve both contexts. The two distribution paths are therefore decoupled: the plugin carries its own MCP config in .claude-plugin/plugin.json (using ${CLAUDE_PLUGIN_ROOT}), while the root .mcp.json is dedicated to the clone workflow (using ${CLAUDE_PROJECT_DIR:-.}). Because plugin.json declares its own mcpServers, the plugin does not also auto-load the root .mcp.json, so there is no double-registration.

Heads-up on scope precedence: project-scope (.mcp.json) outranks user-scope. If you also have an apple-numbers entry registered at user scope (e.g. an absolute path in ~/.claude.json), the project-scope entry wins and the user-scope one is ignored entirely. Pick one — for local development on this repo, the project-scope .mcp.json is the intended source. To pin a specific local build instead, register it at local scope (claude mcp add apple-numbers -s local -- node /abs/path/build/index.js), which outranks project scope.

Requirements

• macOS — the npm package is macOS-only (it declares os: ["darwin"]). Reads and value/structure writes go through numbers-parser directly (no Numbers.app needed); formatting and formula tools additionally require Numbers.app.
• Node.js 20+ — Required for the MCP server
• Python 3.11+ — the numbers-parser library installs automatically into a project-local venv on first use (or pre-warm with pnpm run setup). numbers-parser requires Python ≥ 3.10; macOS ships 3.9, so install a newer Python first (e.g. brew install python@3.12).
• Automation permission (formulas & formatting only) — Reads, exports and ordinary value/structure writes (set-cell(s), add/update/delete-rows, add-sheet/add-table, rename-*, create-spreadsheet, import-csv) need no special permission and no Numbers.app. Only the eight formula/format tools — set-formula(s), set-cell(s)-style, set-column-width/set-row-height, merge-cells/unmerge-cells — drive Numbers.app via AppleScript and require the host app to have Automation permission for Numbers, granted on first use. See the Automation Permission guide. Run the doctor tool to verify your setup.

Features

Read

| Feature | Description | |---------|-------------| | File Inspection | List sheets, tables, dimensions, and header rows | | Table Read | Read data with optional row range and column filtering | | Cell Read | Single cells by 0-based index, with optional formula/format/merge metadata | | Search | Case-insensitive text search across every cell, optionally scoped to one sheet | | Export | Export a table to CSV, TSV, or JSON |

Write

| Feature | Description | |---------|-------------| | Create Spreadsheet | New .numbers file with headers and optional initial rows | | Set Cell | Write a value to a single cell, with optional type coercion | | Set Cells Batch | Write many cells in one operation (more efficient than multiple set-cell calls) | | Add / Update / Delete Rows | Append, replace, or remove rows by index | | Sheets and Tables | Add new sheets or tables to an existing file; rename either |

Formulas (requires Numbers.app)

| Feature | Description | |---------|-------------| | Set Formula | Write a formula like =SUM(B2:B10) to a cell | | Set Formulas Batch | Write many formulas at once |

Formatting (requires Numbers.app)

| Feature | Description | |---------|-------------| | Cell Styles | Font, size, colors, number format, alignment | | Cell Styles Batch | Style many cells at once | | Column Width / Row Height | Set dimensions in pixels | | Merge / Unmerge | Merge a range of cells, or undo a merge |

Import / Diagnostics

| Feature | Description | |---------|-------------| | Import CSV/TSV/JSON | Convert a tabular file into a new .numbers spreadsheet | | Health Check | Verify Python 3 and numbers-parser are installed | | Doctor | Richer setup diagnostic — Python interpreter (path + version), read sidecar, Numbers.app, and Automation permission, each reported ok / warn / fail with actionable advice |

All tools also return structured JSON (`str