HyperFormula Edge Calc Service

Send data and spreadsheet formulas to POST /api/calc and get computed results back as JSON. Accepts raw CSV or JSON arrays. Supports 400+ Excel-compatible functions, named columns, and declarative groupBy aggregation. Read and write .xlsx files directly via the MCP server. Up to 50,000 rows per request.

Try it

Request JSON

Response

Usage

Send a POST to /api/calc with a JSON body. Use GET /api/calc for the full machine-readable API schema.

CSV + Named Columns

Pass raw CSV via the csv field. With headers: true, column names become usable in formulas.

{
  "csv": "Region,Revenue,Cost\nEurope,1000,800\nAsia,2000,1500",
  "headers": true,
  "formulas": ["=SUM(Revenue)", "=SUM(Revenue)-SUM(Cost)"]
}

GroupBy Aggregation

Declarative grouping with SUM, AVERAGE, COUNT, MIN, MAX, or MEDIAN per column. Group values match exactly. Requires headers: true.

{
  "csv": "Region,Revenue,Units\nEurope,1000,5\n...",
  "headers": true,
  "groupBy": {
    "by": "Region",
    "aggregates": { "Revenue": "SUM", "Units": "AVERAGE" }
  }
}

Multi-Formula Mode

Evaluate multiple formulas in one request. Works with data (JSON arrays) or csv.

{
  "data": [[10, 20], [30, 40]],
  "formulas": ["=SUM(A1:A2)", "=AVERAGE(A1:B2)"]
}

Embedded Formulas

Place formulas directly in data cells. Returns the full evaluated grid.

{
  "data": [["a", "b", "sum"], [1, 2, "=A2+B2"], [3, 4, "=A3+B3"]]
}

Excel File Support MCP

When using the MCP server, pass a local .xlsx, .xls, or .csv file path with the file parameter. Optionally write results back as an .xlsx with output_file. Multi-sheet workbooks supported via sheet.

// MCP tool call: calc_formulas
{
  "file": "/path/to/sales.xlsx",           // .xlsx, .xls, or .csv
  "sheet": "Q4",                          // optional, defaults to first
  "headers": true,
  "formulas": ["=SUM(Revenue)", "=AVERAGE(Units)"],
  "output_file": "/path/to/results.xlsx"  // optional write-back
}

The MCP server reads the workbook locally with SheetJS, sends the parsed grid to the calc API, and (when output_file is set) writes the result back as a fresh .xlsx — ideal for filling in computed columns, totals, or grouped rollups in an existing spreadsheet.

Parameters

Param	Description
`csv`	Raw CSV string (alternative to `data`). Numeric values auto-detected.
`data`	2D JSON array (alternative to `csv`).
`headers`	When `true`, row 1 = column names usable in formulas.
`formulas`	Array of formulas. Returns array of values.
`groupBy`	Declarative aggregation: `{by, aggregates}`. Requires `headers`.

Limits

Constraint	Value
Max rows	50,000 (+ header)
Max columns	50
Max body size	50 MB
Max formula length	2,000 chars
Max formulas per request	100
Max CSV cell size	10,000 chars
Max distinct groups (groupBy)	10,000
Rate limit	60 req/min per IP

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included on every response.

Architecture

Stateless Cloudflare Worker. No database, no sessions. Each request is independent. Self-hostable on any platform that supports Node-compatible serverless functions.

MCP Client (remote, URL) MCP Client (local files) Any HTTP Client │ HTTPS │ stdio │ HTTPS │ ┌───────────▼───────────┐ │ │ │ mcp-server.mjs │ │ │ │ (.xlsx/.csv read/ │ │ │ │ write, local) │ │ │ └───────────┬───────────┘ │ ▼ ▼ HTTPS ▼ ┌────────────────────────────────────────────────────────────────────┐ │ Cloudflare Worker │ │ POST /mcp (Streamable HTTP MCP) POST /api/calc │ └─────────────────────────────────┬──────────────────────────────────┘ │ ┌─────────────▼──────────────┐ │ HyperFormula Engine │ │ (stateless, per-request) │ └─────────────┬──────────────┘ │ ┌─────────────▼──────────────┐ │ Usage Analytics │ │ (anonymous, usage only) │ └────────────────────────────┘

The remote MCP endpoint (/mcp) runs on the same Worker — connect any MCP client with just the URL. The local stdio server adds .xlsx file read/write and forwards computation to the hosted API. Rate limiting, hardening, and analytics apply regardless of how the service is accessed.

Performance

Measured against the hosted Worker with a 50,000-row sales dataset (14 columns, 4 MB CSV). Median of three requests, end to end from the client, including upload and server-side CSV parsing.

Mode	Details	Round trip
Formulas + named columns	7 formulas (SUM, AVERAGE, MAX, COUNTA)	~12.5 s
Formulas + cell references	3 formulas, no headers	~4.5 s
GroupBy (2 groups)	by Channel, 3 aggregates	~0.9 s
GroupBy (7 groups)	by Region, 3 aggregates	~1.3 s
GroupBy (12 groups)	by Item Type, 4 aggregates	~1.2 s
GroupBy (180 groups)	by Country, 3 aggregates	~1.0 s
Small dataset	3 rows, 3 formulas	~0.3 s

Formulas and grid modes build a HyperFormula engine per request, so cost grows with data size. GroupBy is a single pass over the rows and is largely independent of the number of groups.

AI Agent Discovery

Machine-readable endpoints for automatic tool discovery:

Endpoint	Description
GET /api/calc	Full API schema — parameters, examples, supported formulas, limits
`POST /mcp`	Remote MCP server (Streamable HTTP) — connect AI agents with just the URL
/openapi.json	OpenAPI 3.1 specification

HyperFormula Edge Calc Service BETA