Open Workbook

Open Workbook is a local-first MCP runtime for fast, reversible, template-aware Excel automation. It connects MCP clients such as OpenCode to live desktop Excel workbooks through an Office.js add-in and a local TypeScript backend, so teams can use OpenRouter or any MCP-capable agent without being locked into one frontier model vendor.

Why

Daily spreadsheet work usually does not need the largest model available, but it does need reliable workbook handling. Open Workbook focuses on the parts generic agents often break:

• preserving templates, headers, formulas, filters, tables, print layout, and styling
• batching reads and writes through Office.js instead of slow per-cell automation
• creating backups and rollback paths before changing workbooks
• keeping workbook data local unless a user explicitly sends it elsewhere
• exposing clear capability status for unsupported or host-limited Excel operations

Current Status

The project is publishable for local development, MCP integration, and sideloaded desktop Excel testing on macOS and Windows. It is not a Microsoft AppSource add-in and does not attempt to install itself into Excel without user or admin trust approval.

Stable areas include runtime connection, workbook/sheet/range operations, reversible batches, snapshots, rollback, templates, style fidelity, formula patterns, tables, filters, sorting, named ranges, regions, validation, repair, cleaning, PivotTables, charts, permissions, packaging, and OpenCode config generation. Some advanced Office.js-limited paths return explicit capability-unavailable results instead of pretending to work.

Architecture

MCP client / agent
       |
       v
apps/mcp-server  -- stdio MCP server
       |
       v
apps/backend     -- local WebSocket broker, plans, backups, snapshots
       |
       v
apps/excel-addin -- Office.js taskpane loaded by desktop Excel
       |
       v
Excel workbook

Shared packages:

• packages/protocol: tool catalog, JSON-RPC contracts, resources, prompts, errors, and workbook types
• packages/excel-core: range parsing, planning, backups, snapshots, templates, permissions, fingerprints, and diffs
• packages/office-js-engine: Office.js execution interface and defaults
• packages/cli: owb CLI for running MCP, serving the add-in, generating manifests, sideloading, and diagnostics

Requirements

• Node.js >=20.11
• pnpm through Corepack
• Desktop Microsoft Excel on macOS or Windows
• An MCP client such as OpenCode
• Network access only for installing packages or using whichever model provider your MCP client calls

Install From Source

git clone https://github.com/open-workbook/open-workbook.git
cd open-workbook
corepack pnpm install
corepack pnpm build
node packages/cli/dist/index.js doctor

Run the MCP server:

node packages/cli/dist/index.js mcp

Serve the Excel add-in assets in a separate terminal:

node packages/cli/dist/index.js addin serve

Generate OpenCode config:

node packages/cli/dist/index.js opencode config --id open-workbook --command "node packages/cli/dist/index.js"

For an installed package, the same commands become:

owb doctor
owb mcp
owb addin serve
owb opencode config --id open-workbook

Sideload Excel Add-in

macOS:

owb sideload mac

Windows:

owb sideload windows --out open-workbook.xml

Windows Excel uses a trusted shared-folder add-in catalog. Create a folder, share it, copy the generated manifest into that shared folder, add the UNC path in Excel Trust Center, select Show in Menu, restart Excel, and insert the add-in from Shared Folder.

More detail is in Local Excel Add-in Sideloading.

Runtime URLs

Defaults:

• Add-in taskpane: http://127.0.0.1:37846/taskpane.html
• Add-in backend: ws://127.0.0.1:37845/addin

Environment overrides:

• OPEN_WORKBOOK_ADDIN_HOST
• OPEN_WORKBOOK_ADDIN_PORT
• OPEN_WORKBOOK_ADDIN_URL
• OPEN_WORKBOOK_HOST
• OPEN_WORKBOOK_PORT
• OPEN_WORKBOOK_ADDIN_PATH
• OPEN_WORKBOOK_BACKUP_DIR
• OPEN_WORKBOOK_PREVIEW_TOOLS=1

Common Commands

corepack pnpm check
corepack pnpm test
corepack pnpm build
node packages/cli/dist/index.js paths
node packages/cli/dist/index.js sideload manifest --out open-workbook.xml

Safety Contract

Mutating operations should follow the same lifecycle:

1. Resolve workbook, sheet, and range targets.
2. Validate permissions, locked regions, and destructive-action policy.
3. Capture affected-region snapshots.
4. Create backups for rollback.
5. Compile writes into batch operations.
6. Check target fingerprints immediately before apply.
7. Apply through Office.js.
8. Validate template, style, formula, table, filter, and layout invariants where requested.
9. Return telemetry, warnings, diff summaries, and rollback IDs.
10. Roll back through stored snapshots when requested or when repair workflows fail validation.

Documentation

• Installation
• Architecture
• Tool Surface
• Backup Lifecycle
• Template System
• Style Fidelity
• Formula Intelligence
• Tables, Filters, and Sorts
• Names and Regions
• PivotTables and Charts
• Advanced Range Reads
• Validation and Repair
• Permissions and Cleaning
• Workbook File Lifecycle
• Performance Contract
• OpenCode Configuration
• Packaging and Publishing
• Sideloading
• Roadmap

Contributing

See CONTRIBUTING.md. The most important rule is that write tools must not bypass planning, snapshots, permission checks, and rollback-aware batches.

Security

Open Workbook handles sensitive spreadsheet data. See SECURITY.md. Workbook content stays local by default; integrations that send data to external services must be explicit and documented.

License

MIT