formulon-mcp

MCP server for Formulon. It uses the published npm package @libraz/formulon@0.11.1 and exposes Excel-compatible formula and .xlsx / .xlsb workbook operations over stdio.

This is designed for agent use: open a workbook once, inspect it, mutate cells, recalculate, read ranges, save, and close the in-memory session. Documents can be authored as well as edited — fonts, fills, ruled borders, number formats and the page setup a printed invoice or receipt needs are all writable from a blank workbook.

Authoring works at two levels. formulon_build_document takes a document as a stack of blocks — title, fields, table, summary — and resolves every position, rule and cross-reference itself, so nothing has to compute which row the total lands on. The primitives (set_cells, style_range, print_settings) then refine the result, using the A1 map the build call hands back.

Install

Requires Node.js 22+. No clone needed — npx fetches and runs the server on demand. The CLI binary is formulon-mcp.

Claude Code

claude mcp add --scope user formulon -- npx -y @libraz/formulon-mcp

Verify with claude mcp list — formulon should report ✓ Connected.

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.formulon]
command = "npx"
args = ["-y", "@libraz/formulon-mcp"]

Claude Desktop

Add to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "formulon": {
      "command": "npx",
      "args": ["-y", "@libraz/formulon-mcp"]
    }
  }
}

Other MCP clients

Any stdio-capable MCP client works. Point it at npx -y @libraz/formulon-mcp, or run formulon-mcp directly after npm install -g @libraz/formulon-mcp.

Interactive setup (optional)

If you'd rather not edit config files by hand for Codex CLI or Claude Desktop, run the bundled installer:

npx -y @libraz/formulon-mcp init

Pick one or more targets (comma-separated, e.g. 1,3,4):

• Claude Code — user (~/.claude.json)

• Claude Code — project (./.mcp.json)

• Codex CLI (~/.codex/config.toml)

• Claude Desktop (claude_desktop_config.json at the platform path above)

Re-running init safely replaces the existing formulon entry without touching other servers. Restart your MCP client to pick up the change.

To remove the entry later:

npx -y @libraz/formulon-mcp uninstall

It drops only the formulon server; other entries are kept.

From source

For development or to pin a fork, clone and build instead of using npm:

git clone https://github.com/libraz/formulon-mcp.git
cd formulon-mcp
yarn install
yarn run build

Then register the absolute path to dist/index.js, e.g.:

claude mcp add --scope user formulon node /absolute/path/to/formulon-mcp/dist/index.js

Or install the latest main directly without a local clone:

npx -y github:libraz/formulon-mcp

Related MCP server: SheetForge MCP

Development

• Node.js 22 via mise

• Yarn 4 with nodeLinker: node-modules

• Biome 2 for format/lint

• TypeScript 7

• Vitest for tests (yarn test, yarn test:watch, yarn test:coverage)

yarn install
yarn run check
yarn run build
yarn run test

Run the server directly for local debugging:

node ./dist/index.js

Tools

• formulon_version: returns the loaded Formulon engine version and the MCP server version.

• formulon_eval_formula: evaluates one Excel formula. With sessionId, it evaluates read-only against an open workbook, resolving references, defined names, and ROW()/COLUMN() anchored at the given cell.

• formulon_open_workbook: creates a workbook session from an .xlsx / .xlsb path, or creates a new default workbook. Anything the reader could not decode is reported as loadLosses on the session.

• formulon_list_sessions: lists open workbook sessions.

• formulon_close_workbook: releases a session.

• formulon_inspect_session: returns sheets, defined names, tables, and optionally sparse cell entries for an open session.

• formulon_set_cells: applies mutations to a session. Cells can be addressed with A1 refs like Sheet1!B2 or zero-based sheet/row/col. Writes are bounds-checked against Excel's grid, and formula cells that evaluate to an error are reported back in errorCells.

• formulon_set_range: writes a 2D block of values from an anchor cell; each element's JSON type picks the cell type, {"f":"=…"} writes a formula, and null skips a cell. Much more compact than set_cells for tables.

• formulon_sheet_operation: adds, removes, renames, or moves sheets.

• formulon_set_defined_name: adds, replaces, or removes defined names, either workbook-scoped or local to one sheet. Print settings such as _xlnm.Print_Area must be sheet-scoped, since Excel ignores a workbook-scoped one without reporting an error.

• formulon_edit_structure: inserts or deletes rows and columns.

• formulon_set_sheet_view: sets zoom, frozen panes, or sheet-tab visibility. visibility reaches all three states — Excel leaves a veryHidden sheet out of its "Unhide" dialog, which hidden cannot express.

• formulon_recalc_session: recalculates an open session.

• formulon_find_cells: searches cell values (text, numbers, booleans) and/or formula text in a session.

• formulon_replace_cells: replaces matching text cell values and/or formula text in a session.

• formulon_inspect_layout: returns stable per-sheet layout data, including used ranges, merges, row/column overrides, protection, cells, calculated values, formulas, and optional style details.

• formulon_detect_regions: detects table-like regions, label-value pairs, and total-like fields with rule-based confidence and evidence.

• formulon_analyze_workbook: classifies workbook shape such as invoice, list, report, schedule, or form using deterministic features and evidence.

• formulon_get_cell: reads one cell from a session or directly from a path, including its formula text (empty for constants). Date/currency/percent cells carry a decoded formatted string alongside the raw value.

• formulon_get_range: reads an A1 rectangular range from a session as a sparse cell list — blanks omitted, clipped to the sheet's used range, and capped at maxCells. Set includeFormulas to annotate computed cells. Formatted numeric cells (dates, currency, percent) carry a decoded formatted string.

• formulon_dimension_operation: lists column-width / row-height overrides, or sets width/height, hidden, or outline level. Columns act on an inclusive [first, last] span; rows act on a single row index.

• formulon_build_document: writes a whole document from a vertical stack of blocks — title, text, fields, table, summary, spacer — resolving positions, ruling, number formats, column widths, merges and the print area from the layout. Blocks reference each other by name rather than by address: a table column registers as {table.<header>} over its body range, and a field or summary item registers under its label, so =SUM({table.Amount}) and ={Subtotal}+{Tax} bind to the right cells once the layout is known — a SUM cannot end up one row short. sameRow puts a block beside the previous one instead of below it. The response maps every block and name to A1, which is what makes the result refinable with the tools below. It carries no document semantics: labels, tax rules and totals are the caller's own formulas.

• formulon_style_range: applies fonts, fills, borders, number formats, and alignment across an A1 range using names and #RRGGBB colors instead of OOXML ordinals. border.all rules every cell, border.outline boxes the range, and both together give a gridded table with a heavier frame. Blank cells are materialized so an empty ruled box renders.

• formulon_default_font: reads or redeclares the workbook default font — the one every cell that was never styled resolves to. A new workbook is seeded with Excel's Calibri 11, so a Japanese document declares its own default once here instead of styling every cell.

• formulon_print_settings: reads or sets page setup, margins, print options, header/footer, print area, print titles, and manual page breaks. A read also reports the resulting pageCount, so a layout can be checked without saving the file.

• formulon_save_session: writes a session out. The container follows the output extension — .xlsb writes XLSB, anything else XLSX — and whatever the writer had to drop or downgrade is reported as losses.

• formulon_session_metadata: reads function names or external links.

• formulon_merge_operation: lists, adds, removes, or clears merged ranges.

• formulon_comment_operation: lists, gets, sets, or removes cell comments.

• formulon_hyperlink_operation: lists, adds, removes, or clears hyperlinks. An added link covers one cell, or the rectangle through lastRow/lastCol; pass location (with an empty target) for an in-workbook destination.

• formulon_validation_operation: lists, adds, removes, or clears data validations. An omitted boolean field on a rule defaults to false, so a rule that should accept empty cells has to spell allowBlank: true.

• formulon_conditional_format_operation: lists, adds, removes, clears, or evaluates conditional formats.

• formulon_trace: reads precedents, dependents, or spill info. Results carry A1 references with sheet names, not raw indices.

• formulon_function_lookup: lists functions and resolves function metadata or localized names.

• formulon_workbook_call: allowlisted low-level access to the Formulon Workbook API for advanced features, including PivotTables, PivotCaches, worksheet tables and their AutoFilter, styles and differential formats, merges, comments, hyperlinks, validations, conditional formatting, sheet display flags such as gridlines and the page-layout view, dependency graph queries, function metadata, spill info, phonetic guides — whole-cell or span by span, with the kana form and alignment they render in — print pagination, the raw print-settings XML fragments, and the workbook clock pin.

• formulon_inspect_workbook: one-shot workbook summary from path.

• formulon_update_workbook: one-shot load/create, mutate, recalc, save.

Unless A1 notation is used, sheet, row, and column indexes are zero-based to match the Formulon API. Operation tools (merge, comment, hyperlink, validation, conditional_format, trace, dimension, print_settings) accept a sheet name in their sheet argument as well as a zero-based index.

style_range treats each property as a delta: a cell keeps whatever the call does not state, so ruling a table does not undo the number format already on its amount column. Style a document in passes — the grid over the whole table first, then the header row, then a total cell. Naming a typeface also cuts the font's theme link, because a theme-linked font is re-resolved from the theme rather than keeping the name it was given; default_font is the workbook-wide counterpart, reaching the cells no style names at all.

build_document is the same idea one level up: reach for it first when writing a document from scratch, and use the primitives on the ranges it names when the result needs adjusting. It is not a substitute for them — it only knows how to stack blocks, and stays out of what any particular document means.

Cell values are returned as {kind, value} envelopes. Formula cells are recalculated when a session is opened, so the first read returns the computed value rather than a blank. Error cells include an errorName Excel literal (#DIV/0!, #REF!, #NAME?, #SPILL!, …) beside the numeric errorCode; the literal comes from the engine, so it covers every error kind the engine can produce. Cells whose number format is a date, currency, or percent carry a numberFormat code, a formatKind, and — for dates and percentages — a decoded formatted string (for example an ISO date), while value keeps the raw Excel serial / number. The full cell style is available through inspect_layout with includeStyles.

Agent Workflow

Open a new workbook:

{
  "path": "input.xlsx",
  "sessionId": "work"
}

Set cells:

{
  "sessionId": "work",
  "mutations": [
    { "type": "number", "a1": "Sheet1!A1", "value": 41 },
    { "type": "formula", "a1": "Sheet1!B1", "formula": "=A1+1" }
  ],
  "recalc": true
}

Read a range:

{
  "sessionId": "work",
  "range": "Sheet1!A1:B1"
}

Search and replace:

{
  "sessionId": "work",
  "query": "budget",
  "target": "both",
  "matchCase": false
}

{
  "sessionId": "work",
  "query": "budget",
  "replacement": "forecast",
  "target": "texts",
  "recalc": true
}

Build a whole document in one call — build_document:

{
  "sessionId": "work",
  "print": "a4-portrait-fit",
  "blocks": [
    { "type": "title", "text": "Invoice" },
    { "type": "spacer" },
    { "type": "text", "name": "to", "text": "Sample Co.", "span": 2 },
    {
      "type": "fields",
      "align": "right",
      "sameRow": true,
      "items": [
        { "label": "No.", "value": "INV-0001" },
        { "label": "Date", "value": "2026-08-22", "format": "date" }
      ]
    },
    { "type": "spacer" },
    {
      "type": "table",
      "columns": [
        { "header": "Item", "key": "name", "width": 30 },
        { "header": "Qty", "key": "qty", "format": "number", "align": "right" },
        { "header": "Unit", "key": "unit", "format": "number", "align": "right" },
        { "header": "Amount", "formula": "={qty}*{unit}", "format": "number", "align": "right" }
      ],
      "rows": [
        { "name": "Design", "qty": 3, "unit": 120000 },
        { "name": "Build", "qty": 5, "unit": 98000 }
      ]
    },
    { "type": "spacer" },
    {
      "type": "summary",
      "items": [
        { "label": "Subtotal", "formula": "=SUM({table.Amount})", "format": "number" },
        { "label": "Tax", "formula": "=ROUND({Subtotal}*0.1,0)", "format": "number" },
        { "label": "Total", "formula": "={Subtotal}+{Tax}", "format": "number", "emphasis": true }
      ]
    }
  ]
}

The response reports where everything landed, which is what the following calls address:

{
  "range": "B2:E13",
  "width": 4,
  "pageCount": 1,
  "names": {
    "title": "B2:E2",
    "to": "B4:C4",
    "Date": "E5",
    "table.header": "B7:E7",
    "table.body": "B8:E9",
    "table.Amount": "E8:E9",
    "Subtotal": "E11",
    "Tax": "E12",
    "Total": "E13"
  }
}

A {name} that matches nothing is an error rather than a formula that quietly points at the wrong range. Braces holding a comma or semicolon are an Excel array constant ({1,2;3,4}) and pass through untouched.

Rule a table and box it — style_range:

{
  "sessionId": "work",
  "range": "Sheet1!B2:E12",
  "style": {
    "border": { "all": "thin", "outline": { "style": "medium", "color": "#1F4E79" } }
  }
}

Then give the header row its own band, without disturbing the ruling:

{
  "sessionId": "work",
  "range": "Sheet1!B2:E2",
  "style": {
    "font": { "bold": true, "color": "#FFFFFF" },
    "fill": { "color": "#1F4E79" },
    "align": { "horizontal": "center" }
  }
}

Make it printable — print_settings:

{
  "sessionId": "work",
  "pageSetup": { "orientation": "portrait", "paperSize": 9, "fitToPage": true, "fitToWidth": 1 },
  "margins": { "left": 0.6, "right": 0.6 },
  "printArea": "B2:E40",
  "printTitles": { "repeatRows": "2:2" },
  "headerFooter": { "oddFooter": "&C&P / &N" }
}

Header and footer text uses Excel's own codes — &L/&C/&R pick the section, &P is the page number, &N the page count, and && a literal ampersand. The engine escapes them for the file, so no caller assembles XML.

Save:

{
  "sessionId": "work",
  "outputPath": "output.xlsx"
}

Low-level API access:

{
  "sessionId": "work",
  "method": "addMerge",
  "args": [0, { "firstRow": 0, "firstCol": 0, "lastRow": 0, "lastCol": 2 }]
}

The low-level tool only dispatches methods explicitly allowlisted in src/sessions.ts. It does not evaluate arbitrary code.

Two low-level calls are worth knowing about:

• setPinnedNow ([year, month, day, hour, minute, second]) pins the workbook clock, so NOW(), TODAY() and the pivot relative-period filters all agree on one instant instead of each reading the host clock. The pin is model state: it is not saved, and clearPinnedNow returns to the host clock.

• pivotCacheSetWorksheetSource must be called on a PivotCache built through the API before saving. A cache with no declared worksheet source produces a file Excel offers to repair, so the writer rejects it.

License

Apache-2.0. See LICENSE.