numbersmcp 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { listSpreadsheets } from "./tools/listSpreadsheets.js";
+import { listSheets } from "./tools/listSheets.js";
+import { readRange } from "./tools/readRange.js";
+import { writeCell } from "./tools/writeCell.js";
+import { writeRange } from "./tools/writeRange.js";
+import { addRow } from "./tools/addRow.js";
+import { readTable } from "./tools/readTable.js";
+import { getFormula } from "./tools/getFormula.js";
+import { setFormula } from "./tools/setFormula.js";
+const server = new McpServer({
+    name: "numbersmcp",
+    version: "0.1.0",
+});
+server.tool("list-spreadsheets", "List all open Numbers documents", {}, async () => {
+    const docs = await listSpreadsheets();
+    return { content: [{ type: "text", text: JSON.stringify(docs, null, 2) }] };
+});
+server.tool("list-sheets", "List all sheets and tables in an open Numbers document", {
+    document: z.string().describe("Name of the open Numbers document"),
+}, async ({ document }) => {
+    const sheets = await listSheets(document);
+    return { content: [{ type: "text", text: JSON.stringify(sheets, null, 2) }] };
+});
+server.tool("read-range", "Read cell values from a range in a Numbers table (e.g. 'A1:C10')", {
+    document: z.string().describe("Name of the open Numbers document"),
+    range: z.string().describe("Cell range in A1 notation, e.g. 'A1:C10'"),
+    sheet: z.string().optional().describe("Sheet name (defaults to first sheet)"),
+    table: z.string().optional().describe("Table name (defaults to first table)"),
+}, async ({ document, range, sheet, table }) => {
+    const rows = await readRange(document, range, sheet, table);
+    return { content: [{ type: "text", text: JSON.stringify(rows, null, 2) }] };
+});
+server.tool("write-cell", "Write a value to a specific cell in a Numbers table", {
+    document: z.string().describe("Name of the open Numbers document"),
+    cell: z.string().describe("Cell reference in A1 notation, e.g. 'B3'"),
+    value: z.string().describe("Value to write to the cell"),
+    sheet: z.string().optional().describe("Sheet name (defaults to first sheet)"),
+    table: z.string().optional().describe("Table name (defaults to first table)"),
+}, async ({ document, cell, value, sheet, table }) => {
+    const result = await writeCell(document, cell, value, sheet, table);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("write-range", "Write multiple values to a range starting at a cell in a Numbers table", {
+    document: z.string().describe("Name of the open Numbers document"),
+    startCell: z.string().describe("Top-left cell reference in A1 notation, e.g. 'A1'"),
+    values: z.array(z.array(z.string())).describe("2D array of string values to write (rows × columns)"),
+    sheet: z.string().optional().describe("Sheet name (defaults to first sheet)"),
+    table: z.string().optional().describe("Table name (defaults to first table)"),
+}, async ({ document, startCell, values, sheet, table }) => {
+    const result = await writeRange(document, startCell, values, sheet, table);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("add-row", "Add a new row at the bottom of a Numbers table", {
+    document: z.string().describe("Name of the open Numbers document"),
+    values: z.array(z.string()).describe("Array of string values for each cell in the new row"),
+    sheet: z.string().optional().describe("Sheet name (defaults to first sheet)"),
+    table: z.string().optional().describe("Table name (defaults to first table)"),
+}, async ({ document, values, sheet, table }) => {
+    const result = await addRow(document, values, sheet, table);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("read-table", "Read an entire Numbers table as structured data", {
+    document: z.string().describe("Name of the open Numbers document"),
+    sheet: z.string().optional().describe("Sheet name (defaults to first sheet)"),
+    table: z.string().optional().describe("Table name (defaults to first table)"),
+    headerRow: z.boolean().optional().default(true).describe("If true, first row is used as keys and rows are returned as objects"),
+}, async ({ document, sheet, table, headerRow }) => {
+    const data = await readTable(document, sheet, table, headerRow);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("get-formula", "Get the formula from a specific cell in a Numbers table", {
+    document: z.string().describe("Name of the open Numbers document"),
+    cell: z.string().describe("Cell reference in A1 notation, e.g. 'A1'"),
+    sheet: z.string().optional().describe("Sheet name (defaults to first sheet)"),
+    table: z.string().optional().describe("Table name (defaults to first table)"),
+}, async ({ document, cell, sheet, table }) => {
+    const result = await getFormula(document, cell, sheet, table);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("set-formula", "Set a formula on a specific cell in a Numbers table (prefix with '=' e.g. '=SUM(B1:B10)')", {
+    document: z.string().describe("Name of the open Numbers document"),
+    cell: z.string().describe("Cell reference in A1 notation, e.g. 'A1'"),
+    formula: z.string().describe("Formula string starting with '=', e.g. '=SUM(B1:B10)'"),
+    sheet: z.string().optional().describe("Sheet name (defaults to first sheet)"),
+    table: z.string().optional().describe("Table name (defaults to first table)"),
+}, async ({ document, cell, formula, sheet, table }) => {
+    const result = await setFormula(document, cell, formula, sheet, table);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tools/addRow.d.ts

@@ -0,0 +1,7 @@
+export declare function addRow(document: string, values: string[], sheet?: string, table?: string): Promise<{
+    success: boolean;
+    document: string;
+    sheet: string;
+    table: string;
+    valuesWritten: number;
+}>;

package/dist/tools/addRow.js

@@ -0,0 +1,31 @@
+import { runAppleScript, escapeForAppleScript } from "@mailappmcp/shared";
+export async function addRow(document, values, sheet, table) {
+    const docEsc = escapeForAppleScript(document);
+    const tableRef = table
+        ? `table "${escapeForAppleScript(table)}"`
+        : "table 1";
+    const sheetRef = sheet
+        ? `sheet "${escapeForAppleScript(sheet)}"`
+        : "sheet 1";
+    const setCmds = values.map((v, i) => {
+        const valEsc = escapeForAppleScript(v);
+        return `set value of cell ${i + 1} of row newRowIndex to "${valEsc}"`;
+    });
+    const script = `
+tell application "Numbers"
+  tell ${tableRef} of ${sheetRef} of document "${docEsc}"
+    set rowCount to row count
+    add row below row rowCount
+    set newRowIndex to rowCount + 1
+    ${setCmds.join("\n    ")}
+  end tell
+end tell`;
+    await runAppleScript(script);
+    return {
+        success: true,
+        document,
+        sheet: sheet ?? "sheet 1",
+        table: table ?? "table 1",
+        valuesWritten: values.length,
+    };
+}

package/dist/tools/getFormula.d.ts

@@ -0,0 +1,7 @@
+export declare function getFormula(document: string, cell: string, sheet?: string, table?: string): Promise<{
+    document: string;
+    sheet: string;
+    table: string;
+    cell: string;
+    formula: string;
+}>;

package/dist/tools/getFormula.js

@@ -0,0 +1,25 @@
+import { runAppleScript, escapeForAppleScript } from "@mailappmcp/shared";
+export async function getFormula(document, cell, sheet, table) {
+    const docEsc = escapeForAppleScript(document);
+    const cellEsc = escapeForAppleScript(cell);
+    const tableRef = table
+        ? `table "${escapeForAppleScript(table)}"`
+        : "table 1";
+    const sheetRef = sheet
+        ? `sheet "${escapeForAppleScript(sheet)}"`
+        : "sheet 1";
+    const script = `
+tell application "Numbers"
+  tell ${tableRef} of ${sheetRef} of document "${docEsc}"
+    set theCell to cell "${cellEsc}"
+    set theFormula to ""
+    try
+      set theFormula to formula of theCell
+      if theFormula is missing value then set theFormula to ""
+    end try
+    return theFormula
+  end tell
+end tell`;
+    const raw = await runAppleScript(script);
+    return { document, sheet: sheet ?? "sheet 1", table: table ?? "table 1", cell, formula: raw };
+}

package/dist/tools/listSheets.d.ts

@@ -0,0 +1 @@
+export declare function listSheets(document: string): Promise<Record<string, string>[]>;

package/dist/tools/listSheets.js

@@ -0,0 +1,19 @@
+import { runAppleScript, escapeForAppleScript, parseRecords } from "@mailappmcp/shared";
+export async function listSheets(document) {
+    const docEsc = escapeForAppleScript(document);
+    const script = `
+tell application "Numbers"
+  tell document "${docEsc}"
+    set output to ""
+    repeat with s in every sheet
+      set sheetName to name of s
+      repeat with t in every table of s
+        set output to output & sheetName & "|||" & (name of t) & "|||" & (row count of t) & "|||" & (column count of t) & "~~~"
+      end repeat
+    end repeat
+  end tell
+  return output
+end tell`;
+    const raw = await runAppleScript(script);
+    return parseRecords(raw, ["sheet", "table", "rowCount", "columnCount"]);
+}

package/dist/tools/listSpreadsheets.d.ts

@@ -0,0 +1 @@
+export declare function listSpreadsheets(): Promise<Record<string, string>[]>;

package/dist/tools/listSpreadsheets.js

@@ -0,0 +1,17 @@
+import { runAppleScript, parseRecords } from "@mailappmcp/shared";
+export async function listSpreadsheets() {
+    const script = `
+tell application "Numbers"
+  set output to ""
+  repeat with doc in every document
+    set docPath to ""
+    try
+      set docPath to path of doc
+    end try
+    set output to output & (name of doc) & "|||" & docPath & "~~~"
+  end repeat
+  return output
+end tell`;
+    const raw = await runAppleScript(script);
+    return parseRecords(raw, ["name", "path"]);
+}

package/dist/tools/readRange.d.ts

@@ -0,0 +1,11 @@
+export declare function parseCellRef(ref: string): {
+    row: number;
+    col: number;
+};
+export declare function parseRange(range: string): {
+    startRow: number;
+    startCol: number;
+    endRow: number;
+    endCol: number;
+};
+export declare function readRange(document: string, range: string, sheet?: string, table?: string): Promise<string[][]>;

package/dist/tools/readRange.js

@@ -0,0 +1,60 @@
+import { runAppleScript, escapeForAppleScript } from "@mailappmcp/shared";
+function colLetterToNum(col) {
+    let n = 0;
+    for (const ch of col.toUpperCase()) {
+        n = n * 26 + (ch.charCodeAt(0) - 64);
+    }
+    return n;
+}
+export function parseCellRef(ref) {
+    const match = ref.toUpperCase().match(/^([A-Z]+)(\d+)$/);
+    if (!match)
+        throw new Error(`Invalid cell reference: ${ref}`);
+    return { col: colLetterToNum(match[1]), row: parseInt(match[2], 10) };
+}
+export function parseRange(range) {
+    const parts = range.split(":");
+    if (parts.length !== 2)
+        throw new Error(`Invalid range: ${range}`);
+    const start = parseCellRef(parts[0]);
+    const end = parseCellRef(parts[1]);
+    return { startRow: start.row, startCol: start.col, endRow: end.row, endCol: end.col };
+}
+export async function readRange(document, range, sheet, table) {
+    const { startRow, startCol, endRow, endCol } = parseRange(range);
+    const docEsc = escapeForAppleScript(document);
+    const tableRef = table
+        ? `table "${escapeForAppleScript(table)}"`
+        : "table 1";
+    const sheetRef = sheet
+        ? `sheet "${escapeForAppleScript(sheet)}"`
+        : "sheet 1";
+    const script = `
+tell application "Numbers"
+  tell ${tableRef} of ${sheetRef} of document "${docEsc}"
+    set output to ""
+    repeat with r from ${startRow} to ${endRow}
+      repeat with c from ${startCol} to ${endCol}
+        set cellVal to value of cell c of row r
+        if cellVal is missing value then
+          set cellVal to ""
+        end if
+        set output to output & (cellVal as text) & "|||"
+      end repeat
+      set output to output & "~~~"
+    end repeat
+  end tell
+  return output
+end tell`;
+    const raw = await runAppleScript(script);
+    if (!raw)
+        return [];
+    const rows = raw
+        .split("~~~")
+        .filter((r) => r.trim())
+        .map((row) => row
+        .split("|||")
+        .slice(0, endCol - startCol + 1)
+        .map((v) => v.trim()));
+    return rows;
+}

package/dist/tools/readTable.d.ts

@@ -0,0 +1 @@
+export declare function readTable(document: string, sheet?: string, table?: string, headerRow?: boolean): Promise<Record<string, string>[] | string[][]>;

package/dist/tools/readTable.js

@@ -0,0 +1,56 @@
+import { runAppleScript, escapeForAppleScript } from "@mailappmcp/shared";
+export async function readTable(document, sheet, table, headerRow = true) {
+    const docEsc = escapeForAppleScript(document);
+    const tableRef = table
+        ? `table "${escapeForAppleScript(table)}"`
+        : "table 1";
+    const sheetRef = sheet
+        ? `sheet "${escapeForAppleScript(sheet)}"`
+        : "sheet 1";
+    const script = `
+tell application "Numbers"
+  tell ${tableRef} of ${sheetRef} of document "${docEsc}"
+    set numRows to row count
+    set numCols to column count
+    set output to ""
+    repeat with r from 1 to numRows
+      repeat with c from 1 to numCols
+        set cellVal to value of cell c of row r
+        if cellVal is missing value then
+          set cellVal to ""
+        end if
+        set output to output & (cellVal as text) & "|||"
+      end repeat
+      set output to output & "~~~"
+    end repeat
+    return output
+  end tell
+end tell`;
+    const raw = await runAppleScript(script);
+    if (!raw)
+        return headerRow ? [] : [];
+    const rows = raw
+        .split("~~~")
+        .filter((r) => r.trim())
+        .map((row) => {
+        const cells = row.split("|||");
+        // Remove trailing empty cell from the trailing ||| before ~~~
+        if (cells[cells.length - 1] === "" || cells[cells.length - 1].trim() === "") {
+            cells.pop();
+        }
+        return cells.map((v) => v.trim());
+    });
+    if (!headerRow) {
+        return rows;
+    }
+    if (rows.length === 0)
+        return [];
+    const headers = rows[0];
+    return rows.slice(1).map((row) => {
+        const obj = {};
+        headers.forEach((h, i) => {
+            obj[h] = row[i] ?? "";
+        });
+        return obj;
+    });
+}

package/dist/tools/setFormula.d.ts

@@ -0,0 +1,8 @@
+export declare function setFormula(document: string, cell: string, formula: string, sheet?: string, table?: string): Promise<{
+    success: boolean;
+    document: string;
+    sheet: string;
+    table: string;
+    cell: string;
+    formula: string;
+}>;

package/dist/tools/setFormula.js

@@ -0,0 +1,20 @@
+import { runAppleScript, escapeForAppleScript } from "@mailappmcp/shared";
+export async function setFormula(document, cell, formula, sheet, table) {
+    const docEsc = escapeForAppleScript(document);
+    const cellEsc = escapeForAppleScript(cell);
+    const formulaEsc = escapeForAppleScript(formula);
+    const tableRef = table
+        ? `table "${escapeForAppleScript(table)}"`
+        : "table 1";
+    const sheetRef = sheet
+        ? `sheet "${escapeForAppleScript(sheet)}"`
+        : "sheet 1";
+    const script = `
+tell application "Numbers"
+  tell ${tableRef} of ${sheetRef} of document "${docEsc}"
+    set value of cell "${cellEsc}" to "${formulaEsc}"
+  end tell
+end tell`;
+    await runAppleScript(script);
+    return { success: true, document, sheet: sheet ?? "sheet 1", table: table ?? "table 1", cell, formula };
+}

package/dist/tools/writeCell.d.ts

@@ -0,0 +1,8 @@
+export declare function writeCell(document: string, cell: string, value: string, sheet?: string, table?: string): Promise<{
+    success: boolean;
+    document: string;
+    sheet: string;
+    table: string;
+    cell: string;
+    value: string;
+}>;

package/dist/tools/writeCell.js

@@ -0,0 +1,20 @@
+import { runAppleScript, escapeForAppleScript } from "@mailappmcp/shared";
+export async function writeCell(document, cell, value, sheet, table) {
+    const docEsc = escapeForAppleScript(document);
+    const cellEsc = escapeForAppleScript(cell);
+    const valueEsc = escapeForAppleScript(value);
+    const tableRef = table
+        ? `table "${escapeForAppleScript(table)}"`
+        : "table 1";
+    const sheetRef = sheet
+        ? `sheet "${escapeForAppleScript(sheet)}"`
+        : "sheet 1";
+    const script = `
+tell application "Numbers"
+  tell ${tableRef} of ${sheetRef} of document "${docEsc}"
+    set value of cell "${cellEsc}" to "${valueEsc}"
+  end tell
+end tell`;
+    await runAppleScript(script);
+    return { success: true, document, sheet: sheet ?? "sheet 1", table: table ?? "table 1", cell, value };
+}

package/dist/tools/writeRange.d.ts

@@ -0,0 +1,8 @@
+export declare function writeRange(document: string, startCell: string, values: string[][], sheet?: string, table?: string): Promise<{
+    success: boolean;
+    document: string;
+    sheet: string;
+    table: string;
+    startCell: string;
+    rowsWritten: number;
+}>;

package/dist/tools/writeRange.js

@@ -0,0 +1,34 @@
+import { runAppleScript, escapeForAppleScript } from "@mailappmcp/shared";
+import { parseCellRef } from "./readRange.js";
+export async function writeRange(document, startCell, values, sheet, table) {
+    const docEsc = escapeForAppleScript(document);
+    const { row: startRow, col: startCol } = parseCellRef(startCell);
+    const tableRef = table
+        ? `table "${escapeForAppleScript(table)}"`
+        : "table 1";
+    const sheetRef = sheet
+        ? `sheet "${escapeForAppleScript(sheet)}"`
+        : "sheet 1";
+    const setCmds = [];
+    for (let r = 0; r < values.length; r++) {
+        for (let c = 0; c < values[r].length; c++) {
+            const valEsc = escapeForAppleScript(values[r][c]);
+            setCmds.push(`set value of cell ${startCol + c} of row ${startRow + r} to "${valEsc}"`);
+        }
+    }
+    const script = `
+tell application "Numbers"
+  tell ${tableRef} of ${sheetRef} of document "${docEsc}"
+    ${setCmds.join("\n    ")}
+  end tell
+end tell`;
+    await runAppleScript(script);
+    return {
+        success: true,
+        document,
+        sheet: sheet ?? "sheet 1",
+        table: table ?? "table 1",
+        startCell,
+        rowsWritten: values.length,
+    };
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "numbersmcp",
+  "version": "0.1.1",
+  "description": "MCP server for macOS Numbers.app — spreadsheet access via AppleScript",
+  "mcpName": "io.github.aernouddekker/numbersmcp",
+  "type": "module",
+  "bin": { "numbersmcp": "./dist/index.js" },
+  "files": ["dist"],
+  "scripts": { "build": "tsc", "start": "node dist/index.js", "prepublishOnly": "npm run build" },
+  "keywords": ["mcp", "mcp-server", "numbers", "spreadsheet", "macos", "applescript", "claude"],
+  "author": "Aernoud Dekker",
+  "repository": { "type": "git", "url": "https://github.com/aernouddekker/macos-mcp.git", "directory": "packages/numbers" },
+  "dependencies": { "@mailappmcp/shared": "*", "@modelcontextprotocol/sdk": "^1.12.0", "zod": "^3.23.0" },
+  "devDependencies": { "typescript": "^5.5.0", "@types/node": "^22.0.0" },
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "os": ["darwin"]
+}