XLSX MCP & Agents

CmdCal XLSX is a good fit for agent workflows because the model can describe a workbook as structured JSON without having to hand-author imperative workbook mutation code.

Local MCP Spreadsheet Tools

The MCP server now exposes three spreadsheet tools:

• generate_spreadsheet
• validate_spreadsheet
• repair_spreadsheet

These run locally and do not require a CmdCal API key.

Typical Flow

1. the agent calls generate_spreadsheet with workbook JSON
2. the tool saves a local .xlsx artifact and returns the file path
3. the agent can pass that artifact path into validate_spreadsheet
4. if needed, the agent can call repair_spreadsheet and save a repaired copy

Example MCP Prompts

Generate A Workbook

Create an Excel workbook with a revenue sheet and save it locally.

Validate An Artifact

Validate the workbook at /Users/you/CmdCal-Output/spreadsheet_2026-03-28T01-00-00.xlsx and summarize the top findings.

Repair A Broken Workbook

Repair the workbook at /Users/you/CmdCal-Output/customer-upload.xlsx, save a repaired copy, and tell me what changed.

Example Spreadsheet Payload

{
  "document": {
    "meta": {
      "title": "Revenue Report",
      "creator": "CmdCal MCP"
    },
    "sheets": [
      {
        "name": "Revenue",
        "rows": [
          {
            "cells": [
              { "value": "Quarter" },
              { "value": "Revenue" },
              { "value": "Closed" }
            ]
          },
          {
            "cells": [
              { "value": "Q1 2026" },
              { "value": 420000 },
              { "value": true }
            ]
          }
        ]
      }
    ]
  },
  "validate_after_render": true,
  "attempt_repair_if_needed": true
}

Download the same starting input here:

• mcp-generate-spreadsheet-input.json

Why This Works Well For Agents

Structured spreadsheet JSON is a better agent surface than imperative workbook code because:

• it is easier to validate
• it is easier to diff and retry
• it matches planning-oriented model output
• it keeps formatting, template, and validation logic inside the engine

Example Tool Inputs

Generate Only

Use generate_spreadsheet with the downloadable JSON payload and let the tool save the .xlsx artifact locally.

Validate Only

Once you have a generated workbook path, pass that path into validate_spreadsheet.

{
  "artifact_path": "/Users/you/CmdCal-Output/quickstart-revenue.xlsx"
}

Repair Only

Use repair_spreadsheet when you already have a suspect workbook and want a conservative salvage pass.

{
  "artifact_path": "/Users/you/CmdCal-Output/customer-upload.xlsx",
  "revalidate_after_repair": true,
  "repair_options": {
    "repair_merges": true,
    "repair_worksheet_dimensions": true,
    "remove_invalid_hyperlinks": true,
    "clip_data_validation_ranges": true,
    "remove_invalid_defined_names": true
  }
}

Template-Backed Assembly

For agent workflows that start from a customer workbook template:

1. parse the template buffer with SpreadsheetEngine.parseTemplate(...)
2. inspect anchors with SpreadsheetEngine.inspectTemplate(...)
3. assemble with SpreadsheetEngine.assembleFromTemplate(...)

Use these sample files:

• template workbook: template-named-ranges-sample.xlsx
• injection payload: template-assembly-input.json

Operational Advice

Use generate_spreadsheet for first render.

Use validate_spreadsheet when the workbook came from a customer, template library, or external export.

Use repair_spreadsheet when you need a conservative salvage pass with explicit repair actions.

For higher-trust workflows, keep both the original and repaired artifact paths in your job logs.

Limits To Know

• the MCP spreadsheet tools currently work with local artifact paths or base64 workbook buffers
• true streaming workbook delivery is still an active roadmap item
• cross-app desktop validation still depends on the target spreadsheet apps being available

That means the current best practice is:

• generate locally
• validate locally
• repair conservatively when needed
• run cross-app QA on the important workbook families you ship repeatedly

For more runnable files, use XLSX Examples & Downloads.