Skip to main content
Glama
tabular-mcp

tabular-mcp

by latbert

tabular-tools

Deterministic tabular-file tools for agents and humans: CSV / JSONL / xlsx local read → validate → convert → sample, as an npm engine (@nopilot/tabular-engine) plus a local-first MCP server (@nopilot/tabular-mcp).

Why not just "read the file"? Agents burn context reading raw files and still miscount rows, miss dirty rows, and mangle quoted CSV. These tools do it deterministically: same input → byte-identical output, every time.

The local-first difference

Most tabular-file MCP servers in the wild (e.g. the Pipeworx "CSV Tools" family, ~235 weekly visitors) run behind a hosted gateway: your file leaves your machine, hits their servers, and comes back. That is a non-starter for anything proprietary, personal, or offline.

tabular-mcp runs entirely on your machine:

hosted CSV/xlsx MCP servers

tabular-mcp

Where your data goes

uploaded to their gateway

never leaves the process

Works offline

no

yes

Extra accounts / API keys

usually yes

none

Deterministic output

not guaranteed

byte-identical (seeded sampling)

Source available

mostly closed

MIT, full tests

Three hard guarantees (enforced by design and tests):

  1. Deterministic action tools, not AI wrappers — no LLM calls anywhere; identical input produces identical output.

  2. Pure local computation — zero network requests, zero external data sources; the whole test suite runs offline.

  3. Runs locally, no hosted gateway — stdio or localhost HTTP, bind 127.0.0.1 by default.

Related MCP server: @mcpx-digital/csv-tools

Tools (MCP)

tabular_inspect

Inspect a local CSV / JSONL / xlsx file: row count, column list, inferred schema (per-column dominant type + full type distribution + empty counts) and a dirty-row report with 1-based file row numbers: format errors, missing/extra columns, type drift vs the inferred schema. CSV header = file row 1; JSONL rows are line numbers.

tabular_convert

Convert: csv → jsonl, jsonl → csv, xlsx → csv/jsonl. Returns content inline and optionally writes to a path. xlsx reads the first sheet by default; allSheets: true reads every non-empty sheet (multi-sheet CSV uses # sheet: <name> separators; JSONL gains a sheet field). Same input → byte-identical output.

tabular_sample

Stream-sample without loading the file: head / tail / seeded random. Random sampling uses a deterministic seeded reservoir — same file + count + seed ⇒ the exact same rows, regardless of stream chunking. Each sampled row carries its file row number.

Install & run

npm install -g @nopilot/tabular-mcp
tabular-mcp                          # stdio (default)
tabular-mcp --transport http --port 9420   # stateless Streamable HTTP on 127.0.0.1

MCP client config (stdio):

{
  "mcpServers": {
    "tabular": { "command": "tabular-mcp" }
  }
}

Engine usage (npm)

import { inspectFile, convertFile, sampleFile } from '@nopilot/tabular-engine';

const report = await inspectFile('data.csv');
// → { format: 'csv', rowCount, columns, columnStats, issues: [{ row, code, column, message }], bom }

await convertFile('data.csv', { to: 'jsonl' });        // → { content, rowCount, sheets }
await convertFile('book.xlsx', { to: 'csv', allSheets: true });

const s = await sampleFile('huge.jsonl', { mode: 'random', count: 50, seed: 'k1' });
// → { mode, totalRows, rows: [{ row: 1234, data: {...} }] } — deterministic

Development

npm install
npm test          # build + typecheck + vitest + determinism harness
npm run determinism   # byte-equality spot checks only
npm run publish:dry   # npm publish --dry-run for both packages

The determinism harness (scripts/determinism-check.mjs) runs every capability twice on identical inputs and asserts byte-equal outputs.

Dependencies & licenses

Runtime dependencies (chosen to be mature, permissive, and maintained; no GPL/AGPL anywhere in the tree):

package

version

license

role

papaparse

^5.7.1

MIT

CSV parse/unparse (handles BOM, quoted newlines, delimiter detection)

exceljs

^4.4.0

MIT

xlsx read (first community-edition xlsx reader with no exploit history; no SheetJS CDN needed)

@modelcontextprotocol/sdk

^1.32.2

MIT

official MCP TypeScript SDK (server only)

zod

^4.6.7

MIT

tool input schema

express

^5.2.1

MIT

HTTP transport host

Transitive notes: all transitive runtime dependencies are MIT/Apache-2.0/BSD/ISC/BlueOak-1.0.0/Unlicense except buffers@0.1.1 (via exceljs → unzipper chain), which ships no license field; its upstream repo (substack/node-buffers) is MIT/X11, matching the author's other packages (binary: MIT, chainsaw: MIT/X11). Recorded here rather than assumed.

License of this project: MIT (see LICENSE).

Publishing

This repo ships to zero registries by itself. See PUBLISH.md for the manual npm publish + MCP registry submission steps.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables language models to run data-quality checks and profiling on local files, using dbt-style assertions like not_null, unique, relationships, and accepted_values.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Turns a local CSV or XLSX table into a full analysis report — summary statistics, duplicate and missing-value diagnostics, top category frequencies, significant pairwise correlations, a Markdown insights writeup, and an Excel workbook with native interactive charts — entirely offline with no uploads, API keys, or pandas dependency. It runs over stdio or streamable-http behind a free anonymous tier that returns an in-band quota signal rather than silently billing.
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to deterministically profile, clean, normalize, and validate tabular data, including locale-aware numbers, dates, text encoding, IDs, and CSV/XLSX/JSON inputs, while flagging ambiguous values instead of guessing.
      6
      166 PyPI
      Business Source 1.1