Work with a live Excel workbook through MCP

Deckary's live document tools let an external AI agent work with the workbook currently open in Excel. Sharing is opt-in for each open workbook, and every change is executed by the Deckary add-in inside the live workbook. The tools and safety rules are the same as for live PowerPoint; this page covers what is specific to Excel.

Start a live session#

1. Open the workbook in Excel and open the Deckary task pane.
2. Sign in with the same Deckary account used during MCP authorization.
3. Turn on MCP sharing in the Deckary AI pane.
4. Ask the agent to call list_live_documents and select the session whose kind is excel.

Read the workbook#

read_live_document without targets returns the workbook outline: every worksheet with its handle (ws_…), name, visibility, used range, tab color and frozen panes, its tables (tb_…) and charts (ch_…), the defined names (nm_…), the calculation mode, and the current selection.

Pass worksheet locators as targets for cell content. ws_… returns the sheet's used range; ws_…!A1:H40, ws_…!5:9 and ws_…!C:E return that window. Each window has calculated values, the formulas of the cells that hold one, and number formats. Formulas and number formats use invariant en-US syntax regardless of the user's Excel language. One read returns at most 20,000 cells and marks a larger window as truncated.

Inspect exact formatting and objects#

inspect_live_objects returns exact truth for:

• A cell window such as ws_…!B2:D20: per-cell values, formulas, fonts, fills, alignment, borders, merges, and notes, plus the conditional formats and data validation that apply. At most 500 cells per window.
• A table (tb_…): range, header and totals rows, style, and columns.
• A chart (ch_…): type, title, legend, anchor cells, and each series' source ranges.
• A defined name (nm_…): its formula and scope.

Render cells and charts#

render_live_document returns Excel's own rendering of a cell window (at most 60 columns by 200 rows) or of a chart. Excel for Mac cannot render cell windows through Office, so there the agent can render charts and inspect cells instead.

Author one worksheet per call#

author_live_document takes one Sheet DSL program, which starts with sheet {. A program creates, patches, moves, or deletes one worksheet. Within that sheet it can write values and formulas, fill a pattern across a range, format cells, size columns and rows, insert or delete rows and columns, merge cells, add notes, conditional formats and data validation, and create or change tables, charts, and defined names.

sheet {
  create "Summary" at after ws_1
  cells [{range:"A1:C1",values:[["Region","Q1","Growth"]]},{range:"A2:B3",values:[["North",120],["South",98]]},{range:"C2",values:[["=B2/100"]],fill:"C2:C3"}]
  formats [{range:"A1:C1",font:{bold:true}},{range:"C2:C3",numberFormat:"0.0%"}]
}

Before the first write, have the agent call describe_authoring_vocabulary with the topics live_documents, excel_dsl, and excel_program_body.

Excel-specific rules:

• A string that starts with = is a formula. Write {text:"=…"} for literal text.
• Writing into a cell that already holds a value or formula requires overwrite:true on that entry. Without it, preflight lists the cells that would be overwritten and nothing changes.
• Clauses run in a fixed order, so inserting or deleting rows shifts the addresses later clauses use.
• Theme colors such as accent1 are resolved to the workbook theme's color when written.
• The result returns the written cells after recalculation, including any error values such as #REF!, and Excel's rendering of the written area.

The version check, applied, version_conflict, and settlement_unknown rules are the same as for PowerPoint. The Deckary AI pane in Excel uses the same program and the same checks, and the two never write to a workbook at the same time.

Know when the session ends#

The session ends when you turn off sharing, sign out, close the Deckary pane, or lose the connection. A newly loaded pane always starts with sharing off.