apple-numbers

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.

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.

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.

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)

Configuration for two more hosts is included — each registers 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. Add the server with hermes mcp add apple-numbers --command npx --args -y apple-numbers-mcp, or merge .hermes-plugin/config.yaml into ~/.hermes/config.yaml. Details: .hermes-plugin/README.md.
• 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:

npm install -g github:sweetrb/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 npm run setup to create a project-local Python venv with numbers-parser pre-installed.