formulon-mcp

MCP server for Formulon. It uses the published npm package @libraz/[email protected] and exposes Excel-compatible formula and .xlsx 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.

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

Development

• Node.js 22 via Volta
• Yarn 4 with nodeLinker: node-modules
• Biome 2 for format/lint
• TypeScript 6

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.
• formulon_eval_formula: evaluates one Excel formula.
• formulon_open_workbook: creates a workbook session from an .xlsx path, or creates a new default workbook.
• 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.
• formulon_sheet_operation: adds, removes, renames, or moves sheets.
• formulon_set_defined_name: adds, replaces, or removes workbook-scoped defined names.
• formulon_edit_structure: inserts or deletes rows and columns.
• formulon_set_sheet_view: sets zoom, frozen panes, or sheet-tab hidden state.
• formulon_recalc_session: recalculates an open session.
• formulon_find_cells: searches text cell values 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.
• formulon_get_range: reads an A1 rectangular range from a session.
• formulon_save_session: writes a session to .xlsx.
• formulon_session_metadata: reads function names or external links.
• formulon_merge_operation: lists, adds, removes, or clears merged ranges.
• formulon_comment_operation: gets, sets, or removes cell comments.
• formulon_hyperlink_operation: lists, adds, removes, or clears hyperlinks.
• formulon_validation_operation: lists, adds, removes, or clears data validations.
• formulon_conditional_format_operation: lists, adds, removes, clears, or evaluates conditional formats.
• formulon_trace: reads precedents, dependents, or spill info.
• 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, styles, merges, comments, hyperlinks, validations, conditional formatting, dependency graph queries, function metadata, and spill info.
• 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.

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
}

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.

License

Apache-2.0. See LICENSE.