pivotkit is Excel's PivotTable for web applications and the command line. People load their data, build a report by dragging fields and take it to Excel. The same report renders again in CI.
Table and Chart are tabs with their own settings, and "+ Add" places a field without dragging. Charts zoom, hide series, stack to 100 % and draw reference lines.
| Who you are | What you want | Quickest start |
|---|---|---|
| A user | a report from your data, by clicking | Try the live demo, then build a first report in six steps with the quick start. |
| An operator | the REST service and the MCP server in your environment | Start the container with one docker run: server in 5 minutes. |
| A user of a running server | a report with curl, PowerShell or an AI client | REST service for curl and PowerShell, MCP server for an AI client. |
| A developer | the report in your application, or reports from your code | Pick the package that fits and build a first report with it: Embed pivotkit. |
Weather data by Open-Meteo.com (CC BY 4.0); contains modified Copernicus Climate Change Service information 2023 (ERA5) and 2019 (ERA5-Land), and ECMWF IFS data (sources).
Live demo · Documentation · Features · Comparison · Security · Security policy · Releases and changelogs
| Build | |
| Documentation | pivotkit.eize.dev. Use a report is for the people who build reports. Embed pivotkit and the API reference are for developers. To try it, open the live demo. Learn with real data walks through weather, countries, earthquakes, Nobel laureates and software end of life. |
| npm | |
| License |
- Where the application allows it, people drop their own CSV, JSON or Excel file onto the report. A preview shows a type for each column. Nothing is uploaded. More: load your own data.
- Dates say what they cover. The footer gives the data's first and last date. A grouping such as "Month of year" says which years it combines. More: dates.
- The export to Excel keeps the layout. The rows behind the report download as CSV or JSON.
- A view is safe JSON: it cannot run code. Reports also come without a browser.
pivotkit rendermakes the same report from the downloaded view and data.pivotkit describe sales.xlsx --suggestmakes a first view from a file's fields. More: command line. - Other programs get reports from a REST service,
with an OpenAPI document and a container image. AI clients get them from an
MCP server. It hands the model only what the
policy shows. A client that can read files or open links can
reach more. One
docker runstarts both, with a token of their own: server in 5 minutes. - The REST service and the MCP server read live data. They read a file, call an HTTP API or run your own code with the caller's parameters: sources. A model gets rows only where the policy shows them: what reaches an AI model.
- The services deliver a report in three ways. It comes back in the answer, where the policy allows it. It reaches people as a download link that expires. The link is bound to the person's sign-in where the data is not open. Or it goes to a store you run, as an upload. More: download links.
pivotkit is for the people who build reports in an application, and for the developers who put it there. It is MIT licensed and comes as:
- a React 18/19 component
- a web component, also in PowerShell Universal apps
- a JavaScript engine for the browser and Node
- a command line
- a REST service and an MCP server
The report in the browser computes on the rows the host passes. It fetches no data. The REST service and the MCP server fetch data from the sources you configure. pivotkit sends nothing home. Network requests lists every request it can make.
The report runs in Chrome and Edge from 111, Firefox from 113 and Safari from 16.4: browser support. The engine, the reports, the CLI, the REST service and the MCP server run in Node 22 or later. What works with pivotkit lists the sign-in providers, MCP clients, data sources and platforms, and how each one was tested.
Measured performance · Tests and CI
| Package | What | Install |
|---|---|---|
| pivotkit-core | The engine in plain JavaScript, with no UI and no framework. | npm install pivotkit-core |
| pivotkit-react | The React 18/19 report builder: field list, drag and drop, table and chart, filters, saved and shared views, export. The host provides React and ECharts. | npm install pivotkit-react react react-dom echarts |
| pivotkit-element | The report builder as the web component <pivot-report>, with its own React. For Angular, PHP and plain HTML. ECharts loads on the first chart. |
npm install pivotkit-element |
| pivotkit-xlsx | A plugin that reads Excel .xlsx workbooks in the browser. It checks a workbook before it parses it. pivotkit-core reads CSV and JSON itself. | npm install pivotkit-xlsx |
| pivotkit-report | Reports without a browser, in Node and the browser. It makes a view over rows into JSON, CSV, XLSX, an SVG chart or a printable HTML report from a template. | npm install pivotkit-report echarts |
| pivotkit-cli | The command line pivotkit. It renders, validates and describes views in CI, with exit codes and --json. |
npm install --global pivotkit-cli |
| pivotkit-server | A REST service over the same operations, with an OpenAPI 3.1 document. Sign-in with tokens or OAuth, and policy profiles. Sources are files or an operator's API: HTTP sources. It is the shared core of the MCP server. pivotkit-server serve runs the REST service, and the MCP endpoint too when pivotkit-mcp is installed beside it. The container image holds both and the CLI. |
npm install --global pivotkit-server pivotkit-mcp |
| pivotkit-mcp | An MCP server. An AI client describes data sources, writes and checks views, and has reports made into files or links. Through the server, the client reads only what the policy shows. The server runs over stdio and Streamable HTTP, with a token or OAuth. | npx -y pivotkit-mcp |
The report builder in React. Try it in the playground:
import { PivotReport } from "pivotkit-react";
import "pivotkit-react/styles.css";
<PivotReport data={rows} defaultView={{ rows: ["Region"], values: [{ field: "Sales", agg: "sum" }] }} onViewChange={save} />The same as a web component, on a page without React. Try it on the example page:
<script type="module" src="/assets/pivotkit-element/dist/index.js"></script>
<pivot-report locale="de-DE" default-view='{"rows":["Region"],"values":[{"field":"Sales","agg":"sum"}]}'></pivot-report>
<script type="module">
const report = document.querySelector("pivot-report");
report.data = rows;
report.addEventListener("pivot-view-change", (e) => save(e.detail.view));
</script>The engine without UI:
import { encode, computePivot, toGrid } from "pivotkit-core";
import { toXlsx } from "pivotkit-core/export";
const data = encode(rows); // an array of objects
const result = computePivot(data, {
rows: ["Region"],
cols: ["Product"],
values: [{ field: "Sales", agg: "sum", format: "currency:EUR" }]
});
const grid = toGrid(result); // cells with merges, totals and formatted text
const xlsx = toXlsx(grid); // Uint8ArrayThe command line, on example files it writes itself:
npx pivotkit-cli example # sales.csv and two views
npx pivotkit-cli render sales.pivotkit.json --data sales.csv -o sales.html
npx pivotkit-cli render sales.csv --rows Region --values sum:Revenue -o by-region.html # no view fileThe REST service and the MCP server in a container, with example data. The server makes a token at its first start. Step by step: server in 5 minutes.
docker run -d --name pivotkit -p 127.0.0.1:3333:3333 -v pivotkit:/var/lib/pivotkit ghcr.io/eizedev/pivotkit:<version>
curl -H "Authorization: Bearer $(docker exec pivotkit pivotkit-server token show admin)" http://127.0.0.1:3333/api/v1/sourcesThe view passed to computePivot is plain JSON. The same object is the saved template, the undo
step and what the UI edits. pivotkit treats it as user input: it cannot run code, and the limits in
LIMITS keep its memory use bounded.
The documentation site has the details for users and developers:
- the engine's API
- the view and its limits
- the component's props
- the element's properties and events
- theming
- security
- the feature list: every feature at a glance, with links to the details
The package READMEs are short npm pages that link there.
Start with these:
- CONTRIBUTING.md - how to set up, change, test and open a pull request.
- PRODUCT.md - what pivotkit is and is not.
- AGENTS.md - layout, commands and code rules. AI assistants start here.
- RELEASING.md - how maintainers release.
npm ci
npm run lint
npm run types
npm test
npm run playground # http://localhost:5173Each package has releases of its own. The GitHub releases
list them with their notes. Each package keeps a CHANGELOG.md:
core, react,
element, xlsx,
report, cli,
server, mcp.
Before you update, read Upgrading.
Versioning says which releases may break things.
MIT. pivotkit draws its charts with Apache ECharts, licensed Apache-2.0.
The icon, header and social preview in assets/ and docs/assets/icon.svg come from
eizedev/brand. Their licence is
CC BY 4.0.
The playground's real data sets keep the licences of their sources. examples/playground/data/SOURCES.md lists them.
