Numbers MCP Server

An MCP (Model Context Protocol) server for reading and writing Apple Numbers spreadsheets.

Features

Read Operations: Get table info, fetch rows with pagination, find rows with flexible conditions
Write Operations: Update rows, add rows, delete rows, batch updates with different values per row
Styling (macOS only): Set row colors, color rows by column value, auto-detect existing color schemes

Tools

| Tool | Description | |------|-------------| | numbers_get_info | Quick overview of a Numbers file (sheets, headers, row count, preview) | | numbers_get_table | Get table data with optional pagination and column filtering | | numbers_find_rows | Find rows matching conditions (equality, contains, gt, lt, gte, lte, ne) | | numbers_update_rows | Update all rows matching a condition to the same values | | numbers_add_row | Add one or more rows to a table | | numbers_delete_rows | Delete rows matching a condition | | numbers_batch_update | Update multiple rows with different values in one operation | | numbers_set_row_color | Set background color of a specific row | | numbers_color_rows_by_value | Color rows based on a column's value (e.g., status) | | numbers_detect_color_mapping | Auto-detect color scheme from existing styling |

Installation

Clone and build:

git clone https://github.com/mycleaningfam/numbers-mcp-server.git
cd numbers-mcp-server
npm install
npm run build

Configuration

Add to your MCP settings (e.g., .mcp.json or Claude Desktop config):

{
  "mcpServers": {
    "numbers": {
      "command": "node",
      "args": ["/path/to/numbers-mcp-server/dist/index.js"]
    }
  }
}

Usage Examples

Get table overview

numbers_get_info({ filePath: "/path/to/file.numbers" })

Find rows with conditions

numbers_find_rows({
  filePath: "/path/to/file.numbers",
  where: { Status: "In Progress" },
  columns: ["ID", "Task", "Status"],
  limit: 10
})

Update rows

numbers_update_rows({
  filePath: "/path/to/file.numbers",
  where: { Status: "Done" },
  set: { Priority: "P1" }
})

Batch update with different values

numbers_batch_update({
  filePath: "/path/to/file.numbers",
  updates: [
    { where: { ID: 1 }, set: { Priority: "P0" } },
    { where: { ID: 2 }, set: { Priority: "P1" } },
    { where: { ID: 3 }, set: { Priority: "P2" } }
  ]
})

Color rows by status

numbers_color_rows_by_value({
  filePath: "/path/to/file.numbers",
  column: "Status",
  colorMap: {
    "Done": { r: 144, g: 238, b: 144 },
    "In Progress": { r: 173, g: 216, b: 230 }
  }
})

Requirements

Node.js 18+
macOS (required for styling features - uses AppleScript to control Numbers app)
Numbers app installed (for styling features)

How It Works

Reading: Uses SheetJS (xlsx) library to parse .numbers files
Writing: Uses AppleScript to update cells via the Numbers app (SheetJS free version cannot write .numbers format)
Styling: Uses AppleScript to set row background colors through Numbers app automation

License

MIT

MCP Servers