Univer: give your AI agent a real spreadsheet — the open office harness, hands-on

Ask a language model to build you a budget and you get a confident wall of numbers in the chat window. Ask it to build the same budget in a real spreadsheet — formulas you can click, cells you can audit, formatting that survives a copy-paste into a deck — and until recently you got apologies. The model had no hands, no grid, no formula engine. CSV output is not a spreadsheet; it is a surrender.

Univer (dream-num/univer) is the missing hands. It calls itself "The Office Harness for AI Agents": an open-source, isomorphic office SDK — spreadsheets, documents, presentations, Bases, Boards, even PDFs — with one TypeScript Facade API that runs in the browser and headless in Node.js. It is a serious codebase: 22,000+ stars, Apache-2.0, a Canvas-rendered grid that scrolls 6 million cells at 50–60 FPS, and a formula engine with 500+ built-in functions. And its maintainers ship a companion project that is exactly the agent harness you are looking for: Univer MCP (dream-num/univer-mcp, MIT), a Model Context Protocol server that lets MCP-compatible AI applications drive spreadsheet operations with natural language.

In this tutorial you will give your AI agent a live workbook: launch a Univer instance, connect it over MCP, and send the agent off to build, format, and audit a real spreadsheet while you watch the cells change. Every command below is taken from the projects' own READMEs and docs.

What you'll need#

• An MCP-compatible AI client: Claude Code, Cursor, Gemini CLI, or an agent you built yourself.
• A Univer API key (free) from the API Keys page at console.univer.ai/apikeys.
• A model with multimodal support — some Univer MCP tools return images, and plain-text mode is currently experimental and not supported yet.
• Optionally, Node.js 18+ and pnpm if you want to run the local start kit instead of the hosted playground.

1. Get an API key#

The hosted MCP endpoint authenticates per key. Sign in at the Univer MCP Console and create a key. Keep it somewhere safe — it goes into your MCP client config as a Bearer token in the next steps.

2. Launch a Univer instance#

Before the agent can touch anything, a Univer instance — the spreadsheet runtime where you watch cells change as the agent works — has to be running. Two supported routes:

• Hosted: open the Univer MCP Playground. Zero install, a live sheet in seconds.
• Local: clone dream-num/univer-mcp-start-kit (Apache-2.0), install dependencies, and run the dev server. It starts on http://localhost:5173 by default.

git clone https://github.com/dream-num/univer-mcp-start-kit.git
cd univer-mcp-start-kit
pnpm install   # or: npm install
pnpm dev       # or: npm run dev

The start kit works out of the box with the open-source version of Univer — no license needed. An optional 30-day trial license unlocks advanced features if you want them later.

3. Connect your agent#

The chain is: MCP host (your agent) → Univer MCP Server → mcp-bridge (a Univer plugin) → the Univer instance. Register the server in your client of choice, pointing it at the hosted endpoint with your key:

Claude Code

claude mcp add --transport http univer-mcp https://mcp.univer.ai/mcp/ -H 'Authorization: Bearer {Your UNIVER_API_KEY}'

Gemini CLI

gemini mcp add --transport http univer-mcp https://mcp.univer.ai/mcp/ --header "Authorization: Bearer {Your UNIVER_API_KEY}"

Any other MCP client (Cursor, custom agents), as JSON:

{
  "mcpServers": {
    "univer": {
      "url": "https://mcp.univer.ai/mcp/?univer_session_id=default",
      "type": "http",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

One detail that will burn you exactly once: univer_session_id must match the session id of your running Univer instance. It defaults to default on both sides, so leave it alone unless you are running multiple instances.

4. Give it a real job#

Now the fun part. Open your agent and hand it a task with a real deliverable, for example:

"In the active Univer workbook, build a Q3 marketing budget sheet: line items in A2:A8, amounts in B2:B8, a total in B10 using SUM, conditional formatting that highlights any amount over 5,000 in red, and a notes column explaining each line item."

The agent now has roughly thirty sheet tools at its disposal, and you can watch it call them in the MCP trace: get_sheets to orient itself, set_range_data to write the line items and amounts, a formula passed straight into a cell value for the total, add_conditional_formatting_rule for the red highlights, set_range_style for the header row, and get_range_data to read everything back and verify its own work. When you ask it to fix a mistake — "move the totals row to B12 and add a data validation rule that rejects negative amounts" — it reaches for set_data_validation_rule and insert_rows the same way.

Two tools deserve a callout for agent work: search_cells, which lets the agent find its own place in a sheet it did not author, and scroll_and_screenshot, which returns a screenshot of the workbook — this is why a multimodal model is recommended. The agent is not guessing at JSON; it is seeing the grid.

What you built#

An agent with a real spreadsheet harness: a live Univer workbook it can create sheets in, write values and formulas to, format, validate, search, and screenshot — all through the standardized MCP interface, which means the same setup works in Cursor, Claude Code, Gemini CLI, or your own agent loop. The workbook persists as IWorkbookData, a plain JSON snapshot (workbook.save() in the Facade API), so you can store, diff, and reload it programmatically. And because the harness is the same Facade API that runs headless in Node.js, this scales from a playground demo to a server-side pipeline where the agent works over real workbooks with no browser at all.

Honest limitations#

• Early stage. The README says it plainly: Univer MCP is in early development. Chart creation, pivot tables, cross-platform support, and real-time collaboration are all marked WIP.
• Multimodal model required. Some tools return images; plain-text mode is experimental and not supported yet. A text-only model will hit walls.
• The hosted endpoint is not self-hosted. The MCP config points at mcp.univer.ai and needs the API key. You can run the Univer instance locally with the start kit, but the MCP bridge endpoint in the documented quick start is hosted.
• Pro features stay commercial. Core SDK, Facade API, plugin system, and the formula engine are open source; collaboration, import/export, charts, pivot tables, and server features live in the separate Univer Pro extension layer.

None of that changes the headline: for the first time, "put it in the spreadsheet" is an instruction an AI agent can actually follow — cells, formulas, formatting, and all.

Related articles