Lets an AI client read and edit spreadsheet cells, recalculate formulas, and export a WorkPaper JSON document.
Also known as proompteng/bilig, bilig, @bilig/workpaper
- Stars
- 35
- Tools
- —
- Downloads, 30 days
- 1,137
- Latest version
- 1.1.0
- Last commit
- Nov 9, 2026
- License
- MIT
What is Bilig MCP?
Bilig lets an AI client read and edit spreadsheet cells, recalculate formulas, and export a WorkPaper JSON document.
Summary generated from the project's README
About Bilig MCP server
Managing spreadsheet-based logic within automated workflows is what Bilig WorkPaper enables for developers and AI agents. It provides a headless runtime that allows an AI client to interact with workbook-shaped models by reading and editing specific cells, triggering formula recalculations, and exporting the results as WorkPaper JSON documents. This approach allows services to own the model state without needing a visual spreadsheet application or a browser-based grid.
Users can deploy this as a local MCP server using stdio to manage private project state or connect via a hosted endpoint for stateless discovery. The server provides specific tools such as list_sheets, read_range, set_cell_contents, and set_cell_contents_and_readback to ensure precise control. It is designed for technical tasks like pricing, quote approvals, and forecast validation where an agent needs to verify that a change to an input cell correctly updates a dependent summary cell.
What you can do with it
- 1Manage persistent workbook stateDevelopers can save the entire workbook state to a JSON file and restore it later to maintain continuity.
- 2Automate pricing and quotesA service can use the headless runtime to process complex pricing models through automated tool calls.
- 3Audit spreadsheet mutationsThe system provides evidence of changes by comparing values before and after an edit operation.
Written from the project's README. Every use case is checked against a quote from it.
How to install Bilig MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Bilig MCP in Claude Code
$ claude mcp add bilig -- npx -y @bilig/workpaperInstall Bilig MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"bilig": {
"command": "npx",
"args": [
"-y",
"@bilig/workpaper"
]
}
}
}Install Bilig MCP in VS Code
.vscode/mcp.json
{
"servers": {
"bilig": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@bilig/workpaper"
]
}
}
}Install Bilig MCP in VS Code CLI
$ code --add-mcp '{"name":"bilig","type":"stdio","command":"npx","args":["-y","@bilig/workpaper"]}'Install Bilig MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"bilig": {
"command": "npx",
"args": [
"-y",
"@bilig/workpaper"
]
}
}
}Install Bilig MCP in Codex
$ codex mcp add bilig -- npx -y @bilig/workpaperInstall Bilig MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.bilig] command = "npx" args = ["-y", "@bilig/workpaper"]
Install Bilig MCP in Gemini CLI
$ gemini mcp add -s user bilig npx -- -y @bilig/workpaperInstall Bilig MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"bilig": {
"command": "npx",
"args": [
"-y",
"@bilig/workpaper"
]
}
}
}Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachableproompteng/bilig is public and reachablegithub.com/proompteng/bilig ↗Pass
- Package names this repository as its source@bilig/workpaper names proompteng/bilig as sourcenpmjs.com/package/@bilig/workpaper ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @bilig/workpapernpmjs.com/package/@bilig/workpaper/v/1.1.0#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/proompteng/bilig ↗Pass
- OpenSSF ScorecardOpenSSF Scorecard 6.6 / 10; weakest: Code-Review 0, CII-Best-Practices 0, Signed-Releases 0scorecard.dev/viewer/?uri=github.com/proompteng/bilig ↗Partial 10/15
- Package name not close to a popular packageNo popular package one edit away from @bilig/workpaperPass
- No critical advisory in the package or its dependencies13 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeinitialize answered with protocol 2025-03-26 in 43 msPass
README
View on GitHubBilig
Keep the workbook model. Run the rule in Node.
Bilig is a TypeScript-native, headless WorkPaper runtime for Node.js services, tests, and AI agents. Set inputs, recalculate formulas, read computed outputs, persist WorkPaper JSON, restore it, and verify the result—without driving Excel or a browser grid.
Docs · Quick start · TypeScript API · MCP · Examples · Discussions
[!NOTE] Bilig is a headless workbook runtime, not a visual spreadsheet app or a claim of full Excel compatibility. If an
.xlsxfile is your contract, start with the compatibility report.
Quick Start
Node runtime
Prove the published package before installing it:
npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json
The evaluator edits Inputs!B2, recalculates Summary!B2, saves the WorkPaper,
restores it, and compares the restored value:
{
"schemaVersion": "bilig-evaluator.v1",
"door": "workpaper-service",
"evidence": {
"editedCell": "Inputs!B2",
"dependentCell": "Summary!B2",
"before": 24000,
"after": 38400,
"afterRestore": 38400
},
"verified": true
}
verified: true means the write, formula readback, JSON export, and restored
readback all passed. It is stronger evidence than a successful write call.
Use It From TypeScript
npm install @bilig/workpaper
import { buildA1WorkPaper } from '@bilig/workpaper'
const pricing = buildA1WorkPaper({
Inputs: [
['Metric', 'Value'],
['Units', 20],
['Price', 1200],
],
Summary: [
['Metric', 'Value'],
['Revenue', '=Inputs!B2*Inputs!B3'],
],
})
const proof = pricing.editAndReadback('Inputs!B2', 32, {
readbackRange: 'Summary!B2',
})
console.log(proof.afterReadback.displayValues[0]?.[0]) // 38400
console.log(proof.verified) // true
pricing.dispose()
For ordinary operations, use set(), setMany(), readMany(), display(),
and saveJson(). Use editManyAndReadback() when multiple inputs must be
committed and verified as one edit. The complete public API is documented in
packages/workpaper/README.md.
The lifecycle is deliberately small:
inputs → formula recalculation → typed readback → JSON persistence → restore verification
Why Bilig
| Capability | What it gives you |
|---|---|
| Workbook-shaped models | Sheets, A1 addresses, formulas, ranges, and named expressions without a spreadsheet UI. |
| Verified mutations | Before/after computed values plus persistence and restore checks. |
| Service-owned state | Portable WorkPaper JSON for routes, queues, tests, tools, and audit trails. |
| Agent-safe tools | Narrow read/write tools with exact cells, computed readback, and writable-sheet boundaries. |
| Explicit file boundaries | Separate XLSX import, export, risk inspection, and Excel-oracle workflows. |
Use Bilig for pricing, quote approval, payouts, forecasts, validation rules, formula-backed workflows, and tests where a service or tool should own the model. Choose a spreadsheet application or hosted spreadsheet API when you need visual editing, collaboration, macros, interactive pivots or charts, or desktop fidelity.
Agents And MCP
Agents should first ask which system owns state, then run the smallest matching proof. For a tool host or MCP client:
npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --json
npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json
The MCP evaluator proves tool discovery, mutation, recalculated readback, JSON export, disk persistence, process restart, and restored readback. For a local, writable WorkPaper:
npm exec --yes --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable
Use that local stdio path for private or persistent project state. The hosted
https://bilig.proompteng.ai/mcp endpoint is request-local and only intended
for stateless connector discovery and smoke tests; do not send private workbook
data to it.
The server exposes list_sheets, read_range, read_cell,
set_cell_contents, set_cell_contents_and_readback,
get_cell_display_value, export_workpaper_document, and validate_formula.
It also publishes MCP resources and prompts so capable hosts can discover the
workflow before editing cells.
Machine-readable entry points:
| Need | Entry point |
|---|---|
| A compact routing card | docs/agent-start.txt |
| A concise model index | docs/llms.txt |
| Full agent documentation | docs/llms-full.txt |
| Installation context | docs/llms-install.md |
| Structured capabilities | docs/agent.json |
| Reusable skill | skills/bilig-workpaper/SKILL.md |
| Proof and host matrix | docs/agent-adoption-kit.md |
The published package also carries AGENTS.md and SKILL.md, so an agent can
discover the same proof contract from node_modules. Install or inspect the
public skill with either source:
npx --yes skills@latest add https://bilig.proompteng.ai --list
npx --yes skills@latest add proompteng/bilig --skill bilig-workpaper --list
Use the agent rule chooser or the
host handoff prompt.
The repository includes CLAUDE.md,
.claude/skills/bilig-workpaper/SKILL.md,
.claude/commands/bilig-workpaper-proof.md,
.cursor/rules/bilig-workpaper.mdc, .devin/rules/bilig-workpaper.md,
.windsurf/rules/bilig-workpaper.md, .clinerules/bilig-workpaper.md,
.continue/rules/bilig-workpaper.md, .zed/settings.json, opencode.jsonc,
and .opencode/agents/bilig-workpaper.md.
Integration Recipes After The Proof
Run an evaluator first, then use the recipe owned by your host:
- OpenAI Agents SDK: direct tools,
MCPServerStdio, andMCPServerStreamableHttp. - OpenAI Responses API: function-call readback with explicit before/after evidence.
- Vercel AI SDK:
generateText()andstreamText()tool loops. - Open WebUI: local or hosted MCP discovery.
- n8n: the
@bilig/n8n-nodes-workpapercommunity node.
Choose An Evaluation Path
| Your state owner | Start here | Evidence to require |
|---|---|---|
| TypeScript application | npm install @bilig/workpaper |
direct A1 API and focused application tests |
| Node service, route, queue, or test | bilig-evaluate --door workpaper-service --json |
edit, recalculation, JSON export, restore, verified: true |
| MCP client or tool host | bilig-evaluate --door agent-mcp --json |
discovery, readback, disk persistence, restart |
Imported .xlsx is the contract |
workbook-compatibility-report workbook.xlsx --json |
unsupported formulas and workbook risk reasons for that file |
Cached .xlsx values look stale |
xlsx-cache-doctor workbook.xlsx --json |
stale-cache diagnosis, recalculation, and readback for that file |
The workbook-compatibility and xlsx-cache evaluator doors use bundled demo
workbooks to smoke-test the published package; they do not inspect your file.
Do not treat any evaluator as proof of desktop Excel parity.
Examples And Deeper Guides
Start with one maintained example, not the whole monorepo:
examples/headless-workpaper: pricing, invoice, budget, fulfillment, subscription, persistence, and agent examples.examples/serverless-workpaper-api: quote approval through Hono, Next.js, and persistence adapters.examples/xlsx-recalculation-node: import, recalculate, export, reimport, and verify an XLSX workbook.examples/recalc-bridge-workflows: focused bridges for existing SheetJS, xlsx-populate, and ExcelJS workflows.
Useful decision guides:
- Formula workbooks proof page
- Agent evaluator matrix
- MCP spreadsheet server for coding agents
- Vercel AI SDK formula readback
- OpenAI Responses tool calls
- ExcelJS formula result boundary
- Google Sheets
QUERYandSORTN - Microsoft Graph Excel boundary
- XLSX formula support answers
- Production adoption checklist
pnpm --dir examples/headless-workpaper run agent:ai-sdk-generate-text
pnpm --dir examples/headless-workpaper run agent:ai-sdk-stream-text
pnpm --dir examples/headless-workpaper run agent:openai-responses
pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight
pnpm --dir examples/serverless-workpaper-api run hono-route
pnpm --dir examples/serverless-workpaper-api run next-server-action
pnpm --dir examples/serverless-workpaper-api run next-server-action-formdata
The AI SDK generateText() smoke lives at
ai-sdk-generate-text-tool-smoke.ts.
The OpenAI example is documented in
openai-responses-workpaper-tool-call.
For a reduced formula or import bug:
npm exec --yes --package @bilig/workpaper@latest -- bilig-formula-clinic ./reduced.xlsx --cells "Summary!B7,Inputs!B2"
XLSX And Excel Compatibility
Bilig can import and export workbook files, but cached formula values inside an
.xlsx are diagnostics—not an accuracy oracle. Inspect the file before trusting
it:
npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door workbook-compatibility --json
npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- workbook-compatibility-report workbook.xlsx --json
npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-cache-doctor workbook.xlsx --json
The first command is a package smoke test over a bundled demo. The next two inspect the named file. The compatibility report identifies unsupported functions, external links, macros, pivots, volatile formulas, and other risks; it does not certify Excel compatibility. When correctness matters, compare against a workbook freshly recalculated by Excel. See the compatibility limits and Excel oracle walkthrough.
Packages And Repository Map
| Path | Role |
|---|---|
packages/workpaper |
Recommended @bilig/workpaper API, evaluators, AI SDK adapter, MCP server, and XLSX boundary. |
packages/xlsx-formula-recalc |
Real-file compatibility and stale-cache diagnostics. |
packages/formula |
Formula parser, binder, compiler, and evaluator. |
packages/core |
Workbook state, mutations, snapshots, and scheduling. |
apps/web |
Browser spreadsheet shell. |
apps/bilig |
Full-stack runtime, APIs, and static site host. |
The public WorkPaper package requires Node.js >=24. Local monorepo development uses
Node.js 24+, Bun, and pnpm@10.32.1.
Published releases include npm registry signatures and provenance attestations:
npm view @bilig/workpaper version dist.attestations dist.signatures --json
npm audit signatures
Development
Choose one long-running development server:
pnpm dev:web
pnpm dev:web-local
Install and validate the repository with:
pnpm install
pnpm build
pnpm lint
pnpm typecheck
pnpm test
pnpm run ci
Architecture lives in docs/architecture.md. Read
CONTRIBUTING.md before opening a pull request; first-time
contributors can start with the new contributor guide
and starter issues. All participation follows the
CODE_OF_CONDUCT.md.
Support And Security
- Ask adoption and design questions in Discussions.
- Follow versioned changes through GitHub Releases.
- Report reproducible bugs through Issues; reduced workbooks can use the formula bug clinic and fixture form.
- Read
SUPPORT.mdfor the evidence that makes a report actionable. - Follow
SECURITY.mdfor private vulnerability reporting. Never attach private workbook data, credentials, or tokens to a public issue.
If Bilig fits one of your services or agent workflows, star the repository to follow releases and help other Node developers find it. Tell us what proof or formula is still missing.
License
Bilig MCP questions
How do I add Bilig MCP to Claude Code?
Run claude mcp add bilig -- npx -y @bilig/workpaper in your terminal. Add --scope user to make it available in every project.
How do I add Bilig MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does the Bilig MCP server expose?
It exposes tools to list sheets, read ranges and cells, write cell contents with or without readback, get display values, export the WorkPaper document, and validate formulas.
How do I run the Bilig MCP server locally?
Run the bilig-workpaper-mcp command pointing at a WorkPaper JSON file, optionally initializing a demo workbook and enabling writes.
Can I use the hosted Bilig MCP endpoint for private workbooks?
No, the hosted endpoint is request-local and meant only for stateless discovery and smoke tests. Use the local stdio path for private or persistent state.
Does Bilig fully match Excel?
No, Bilig is a headless workbook runtime and does not claim full Excel compatibility. Check the compatibility report if an .xlsx file is your contract.
Does the Bilig MCP server require authentication?
The README does not describe API keys or OAuth; the documented setup uses a local stdio command with a file path.