Numera

@vectojs/numera-mcp is the safe local-first Model Context Protocol adapter for Numera workbooks. It lets an MCP client inspect workbooks, read bounded ranges, and write validated cell batches without launching a browser or subprocess. The published stdio executable requires Bun.

The server supports .numera.json, .json, .csv, and .xlsx files through exact-pinned Numera Core and XLSX packages. It is intentionally local and does not provide collaboration, accounts, cloud storage, or remote network access.

Run

numera-mcp --root /absolute/path/to/workbooks

The server uses stdio. Paths passed to tools are relative to --root. Mutation tools require an expected input SHA-256 and a distinct, non-existing output path, so a stale Agent cannot silently overwrite newer work.

Tools

• numera_inspect_workbook: return the format, SHA-256, active sheet, sheet dimensions, populated-cell count, and used range.
• numera_read_range: return raw and display values for at most 10,000 cells.
• numera_write_cells: validate and atomically apply 1–1,000 typed cell writes to a new output workbook.

Development

bun install
bun run verify
npm pack --dry-run

Security

See SECURITY.md. Numera MCP treats workbook bytes, formulas, paths, and MCP arguments as untrusted input.