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.
Power your agent
Yayıncının kendi komutu. PlugMCP uç noktası değildir.
Host a copy with our keys and logs.
npx -y [email protected]Claude Code'un yerel komutlar için kurulum bağlantısı yok. Aşağıdaki komutu kopyalayın ve bir terminalde çalıştırın.
claude mcp add apple-numbers-mcp -- npx -y apple-numbers-mcp@1.3.5Bir terminalde çalıştırın.
{ "mcpServers": { "apple-numbers-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
Uzak URL mi, yoksa makinenizde bir komut mu? İki kurulum arasındaki fark
PlugMCP’de çalıştır
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
BaşlatYayıncıdan
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.
MCP server for Apple Numbers - read, write, search, and format .numbers spreadsheets via Claude and other AI assistants
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:
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.
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
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 [email protected] first). To pre-warm it instead of waiting on the first call, run scripts/setup.sh inside that install directory.
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.
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).
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?"
.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_ROOTis 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 useCLAUDE_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.jsonis dedicated to the clone workflow (using${CLAUDE_PROJECT_DIR:-.}). Becauseplugin.jsondeclares its ownmcpServers, 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 anapple-numbersentry 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.jsonis 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.
os: ["darwin"]). Reads and value/structure writes go through numbers-parser directly (no Numbers.app needed); formatting and formula tools additionally require Numbers.app.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 [email protected]).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.All tools also return structured JSON (structuredContent) alongside the human-readable text, so agents can consume results without parsing prose.
Resources expose read-only context the client can attach without a tool call:
the numbers://file/{path} template (file structure — sheets, tables, dimensions,
headers) and the numbers://table/{path} template (the default table's data).
Both are templated by a URL-encoded .numbers file path. Prompts package common
workflows: analyze-spreadsheet, bulk-edit, import-csv-guide.
This section documents all available tools. AI agents should use these tool names and parameters exactly as specified.
health-checkVerify Python 3 and numbers-parser are installed and reachable from the server.
Parameters: None
Returns: numbers-parser version, or an error explaining how to install.
doctorRun a full setup diagnostic with four separate checks: python_interpreter (the resolved Python's path and version — warns when it's older than 3.11, the most common setup failure since stock macOS ships 3.9), numbers_parser (the read sidecar — required for all reads/exports), numbers_app (Numbers.app present — required for the formula/format tools only), and automation_permission (an informational reminder that those tools need Automation permission for Numbers.app). Each is reported as ok / warn / fail with actionable advice. This is the richer counterpart to health-check; reach for it first when a tool returns a permission or setup error.
Parameters: None
Returns: A per-check report. The structuredContent carries the raw { healthy, checks[] }, where each check has name, status (ok/warn/fail), and detail. Only the formula/format tools need Automation permission — see docs/AUTOMATION-PERMISSION.md.
get-file-infoGet the structure of a .numbers file: sheets, tables, dimensions, header rows.
Returns: Default sheet name, plus each sheet with its tables (name, dimensions, header row).
read-tableRead data from a table. Returns headers and rows. Defaults to the first sheet and first table if not specified.
Returns: Sheet name, table name, the headers and rows selected, and numRows / numCols describing the selection — not the table. When you pass startRow/endRow/columns, those counts describe what came back; use get-file-info for the table's real dimensions.
get-cellRead a single cell value by row and column index (0-based).
searchCase-insensitive partial match across every cell in a .numbers file.
Returns: Each match with sheet, table, row, column header, and value.
export-tableExport a table to CSV, TSV, or JSON.
⚠️ Safety: Writes a file to disk at outputPath. An existing file there is refused unless you pass overwrite: true — confirm with the user before passing it. Paths are bounded: outputPath must resolve — after ~ expansion and symlink resolution — to a location under your home directory, /tmp, /private/tmp, or /Volumes; anything else is rejected with an error naming those roots.
create-spreadsheetCreate a new .numbers file with one sheet and table.
⚠️ Safety: An existing file at path is refused unless you pass overwrite: true — confirm with the user before passing it. Paths are bounded: path must resolve — after ~ expansion and symlink resolution — to a location under your home directory, /tmp, /private/tmp, or /Volumes; anything else is rejected with an error naming those roots.
set-cellWrite a value to a single cell.
⚠️ Safety: Overwrites the existing cell value in place in the .numbers file.
set-cells-batchWrite multiple cells in a single operation. Much more efficient than multiple set-cell calls.
⚠️ Safety: Overwrites the existing cell values in place in the .numbers file.
add-rowsAppend rows of data after the last existing row.
update-rowsWrite full rows by index. Each update is a complete row replacement.
⚠️ Safety: Overwrites the existing row data in place in the .numbers file.
delete-rowsDelete a range of rows by 0-based inclusive indices.
⚠️ Safety: Destructive and not undoable — requires explicit user confirmation. Modifies the .numbers file in place; verify the row range first.
add-sheetAdd a new sheet, optionally with headers for the default table.
Table geometry: pass headers and the new table is created 1 row × headers.length columns; omit them and you get a 12 × 8 grid of empty cells. There is no way to override the size through MCP — delete the extra rows with delete-rows if you don't want them. The response reports the dimensions that were created.
add-tableAdd a new table to an existing sheet.
Table geometry: same rule as add-sheet — with headers the table is 1 × headers.length, without them 12 × 8.
rename-sheet / rename-tableRename a sheet or table. You identify the target by its current name via the optional sheet / table parameters (omit them to target the first sheet / first table); there is no oldName input — the old name is returned in the result, not passed in.
rename-sheet
rename-table
set-formulaWrite a formula to a cell.
set-formulas-batchWrite multiple formulas in a single operation.
set-cell-styleApply font, color, number format, and alignment to a single cell.
style object fields (all optional; omit a field to leave it unchanged):
Example: { "fontName": "Helvetica-Bold", "fontSize": 14, "textColor": { "red": 65535, "green": 0, "blue": 0 }, "alignment": "center" }
set-cells-style-batchApply styles to multiple cells in a single operation.
set-column-width / set-row-heightSet the width of a column or height of a row in pixels.
merge-cells / unmerge-cellsMerge a rectangular range of cells, or undo a merge.
import-csvImport a CSV, TSV, or JSON file into a new .numbers spreadsheet. Auto-detects format from extension, or pass format explicitly.
⚠️ Safety: An existing file at outputPath is refused unless you pass overwrite: true — confirm with the user before passing it. Paths are bounded: both inputPath and outputPath must resolve — after ~ expansion and symlink resolution — to locations under your home directory, /tmp, /private/tmp, or /Volumes; anything else is rejected with an error naming those roots.
CSV/TSV fields are auto-typed. Every field from a csv/tsv source is converted before it is written: "" → empty cell, true/false → boolean, and anything Python's int()/float() parses → number. So a zip code 01234 becomes the number 1234, 007 becomes 7, and 1e5 becomes the number 100000. This is deliberately less conservative than set-cell/add-rows, which keep leading-zero strings intact, and there is no per-column type control on import. For zero-padded identifiers, import from JSON instead (JSON values are passed through untouched) or repair the column afterwards with set-cells-batch using type: "string".
JSON column sets come from the first object. For an array of objects, the columns are the keys of data[0]; a key that appears only in a later object is dropped and objects missing an early key get blank cells — normalize the keys first. For an array of arrays, columns are named Column_0, Column_1, … and the first row is kept as data.
format: "auto" falls back to CSV. Any extension that isn't .csv, .tsv or .json is parsed as comma-separated rather than erroring, so pass format explicitly for unusual extensions. The format actually used is echoed back in the result.
User: "What's in ~/Documents/budget.numbers?"
AI: [calls get-file-info]
"It has 3 sheets: Q1, Q2, Q3. Q1 contains a 'Budget' table with 12 rows × 5 columns..."
User: "Show me Q3"
AI: [calls read-table with sheet='Q3']
"Q3 / Budget (12 rows × 5 cols): ..."
User: "Find every line about Acme Corp"
AI: [calls search with query='Acme Corp']
"Found 4 matches in Q1/Budget and Q3/Vendors..."
User: "Set B5 to =SUM(B2:B4) and bold the header row"
AI: [calls set-formula] [calls set-cells-style-batch with style {fontName: "Helvetica-Bold"} on row 0]
"Done — B5 is =SUM(B2:B4) and the header row is bold."
User: "Import ~/Downloads/customers.csv into a new spreadsheet"
AI: [calls import-csv with inputPath, outputPath]
"Imported 240 rows (6 columns) into ~/Documents/customers.numbers"
npm install -g apple-numbers-mcp
pip3 install numbers-parser
git clone https://github.com/sweetrb/apple-numbers-mcp.git
cd apple-numbers-mcp
pnpm install
pnpm run setup # creates ./venv and installs numbers-parser
pnpm run build
Installing the repo directly from GitHub (npm install -g github:sweetrb/apple-numbers-mcp) also counts as a from-source install: it runs the repo's build on your machine and requires pnpm. Prefer the published npm package above unless you specifically want unreleased code.
If installed from source, use this configuration:
{
"mcpServers": {
"apple-numbers": {
"command": "node",
"args": ["/absolute/path/to/apple-numbers-mcp/build/index.js"]
}
}
}
The server prefers a project-local venv at ./venv/bin/python3 if present, and falls back to system python3. Global npm install works fine as long as numbers-parser is on the system Python.
All configuration is optional — the server works out of the box.
Per-call timeouts are not configurable. Every
numbers-parsersidecar call runs under a fixed 30-second timeout and every AppleScript call under a fixed 60-second one; there is no environment variable for either.APPLE_NUMBERS_MCP_SETUP_TIMEOUTabove governs only the one-time venv bootstrap, andAPPLE_NUMBERS_MCP_MAX_BUFFERcaps stdout size, not wall-clock time. If you hitOperation timed out after 30000ms, narrow the request — useread-table'sstartRow/endRowandcolumns, split large batches — rather than looking for a knob.
env)Some host apps (e.g. Claude Desktop) launch the MCP server with a scrubbed
environment and ignore the env block in their server config, so there's no way
to pass APPLE_NUMBERS_MCP_* settings through it. In that case, put them in a JSON
file the host doesn't manage — APPLE_NUMBERS_MCP_CONFIG_FILE, or by default
~/Library/Application Support/apple-numbers-mcp/config.json:
{
"APPLE_NUMBERS_MCP_MAX_BUFFER": "104857600"
}
The server reads it at startup and merges string values into the environment
without overriding anything already set there (so an explicit env still
wins). Keep only non-secret config here.
This package is a TypeScript MCP server with a Python sidecar:
src/utils/numbers_reader.py) uses numbers-parser to read and write .numbers files and returns JSON.src/utils/applescript.ts) drives Numbers.app directly — numbers-parser doesn't write styles.child_process.execFileSync.This is the same Python-sidecar pattern used by apple-photos-mcp for the osxphotos library.
For the full rundown — the values-vs-formatting backend split, AppleScript-only
formulas/styles, import-csv auto-typing, fixed per-call timeouts, indexing,
dates, format lag, and concurrent edits — see docs/LIMITATIONS.md.
The summary below is the quick version.
These are tracked for future releases. The underlying numbers-parser library has partial support for styles via its Style API, which provides a path forward for some of these.
python3 is older than 3.11 — stock macOS ships Python 3.9, which numbers-parser can't run on. Install a newer Python (brew install [email protected]), then simply retry the tool call: the venv rebuilds automatically.pip3 install numbers-parser (global Python), or run scripts/setup.sh from a repo checkout (pnpm run setup) to build the project-local venv.doctor tool — it reports the resolved Python interpreter path and version, so a too-old stock Python is visible at a glance../venv/ in the project directory.apple-numbers server fails to connect when run from a cloneclaude from inside the repo directory so CLAUDE_PROJECT_DIR resolves to the repo root (the bare . fallback is unreliable).pnpm run build and pnpm run setup first — build compiles the entrypoint, setup creates the ./venv the Python sidecar needs.claude mcp list to check for conflicting scopes; project-scope .mcp.json outranks a user-scope apple-numbers entry, and a local-scope entry outranks both.Tool '<name>' has an invalid outputSchema: JSON Schema declares an unsupported dialect ("$schema": "http://json-schema.org/draft-07/schema#"). The default validator supports JSON Schema 2020-12 only. The host refuses every tool, so the server looks completely dead even though it started fine.https://json-schema.org/draft/2020-12/schema on every tool's inputSchema and outputSchema.npx -y apple-numbers-mcp, restart the host to pick up the new version; if you run from a clone, git pull && pnpm install && pnpm run build.~ if your shell isn't doing it..numbers./tmp, /private/tmp, and /Volumes — the server will not write into /etc, /Library, an app bundle, or any other system location, and will not read from one..numbers file itself, not just export/import destinations. get-file-info, read-table, search and the in-place writes (set-cell, add-rows, set-formula, …) previously accepted a path anywhere on disk.~/Documents/report.numbers, /tmp/report.csv). If your spreadsheets genuinely live somewhere else, add that directory to APPLE_NUMBERS_MCP_EXTRA_ROOTS — see Environment variables.tccutil reset AppleEvents.doctor tool to confirm your setup — it reports the Numbers.app and Automation-permission checks separately. See the Automation Permission guide. Reads don't need this permission; only writes do.1e-9 of an integer. If you want raw values, file an issue.pnpm install # Install dependencies
pnpm run setup # Create ./venv with numbers-parser
pnpm run build # Compile TypeScript
pnpm test # Unit tests (mocked)
pnpm run test:integration # Integration tests against real .numbers fixtures
pnpm run test:all # Both
pnpm run test:coverage # Unit tests with coverage report
pnpm run typecheck # Type-check without emitting
pnpm run lint # Check code style
pnpm run format # Format code
Integration tests exercise the full pipeline against real .numbers fixture files. Generate the fixtures first, then run:
pnpm run setup
./venv/bin/python3 test/fixtures/generate-fixtures.py
pnpm run test:all
Unit tests run everywhere; integration tests auto-skip when fixtures or numbers-parser are not available.
Rob Sweet - President, Superior Technologies Research
A software consulting, contracting, and development company.
MIT License - see LICENSE for details. This project is not affiliated with Apple Inc. or the numbers-parser project.
Contributions are welcome! Please open an issue or PR at github.com/sweetrb/apple-numbers-mcp.
Part of a family of macOS MCP servers:
If macOS keeps re-prompting for Full Disk Access or Automation for node (often after a brew upgrade), see docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md — the fix is to run this server under the official, Developer-ID-signed Node so the grant survives Node updates.
MCP server for Apple Numbers - read, write, search, and format .numbers spreadsheets via Claude and other AI assistants
{ "mcpServers": { "apple-numbers-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}Araçlar
Henüz araç listesi yok. Uzak sunucular ilk sağlık kontrolünden sonra bir liste alır.
SSS
Bu sayfadan Cursor, Claude Desktop, Claude Code veya VS Code için stdio yapılandırmasını kopyalayın. PlugMCP proxy'sini değil, yayıncının kurulumunu kullanır.
Bu kayıtta gerekli bir ortam değişkeni listelenmiyor.
Apple Numbers yerel olarak stdio üzerinden çalışır.
Son kontrol: 2026-11-16. MCP server for Apple Numbers - read, write, search, and format .numbers spreadsheets via Claude and other AI assistants