Deterministic Excel Backend for LLM Agents (MCP)

This actor provides a deterministic Excel backend for LLM agents and automated workflows.

Unlike CSV exports or ad-hoc spreadsheet generation, this actor lets agents safely read, write, and update real Excel files while preserving:

• formulas
• formatting
• sheet structure
• predefined schemas

It is designed for agent pipelines, MCP-based tools, and production workflows where Excel is the final, auditable output — not a temporary artifact.

No Excel installation required — uses pure Python with openpyxl.

Features

• Read/Write cells and ranges — Access any data in your spreadsheets
• Formula support — Get and set Excel formulas
• Sheet management — Create, delete, and list worksheets
• Export options — Convert to JSON or CSV
• No dependencies — Works without Microsoft Excel installed
• MCP Protocol — Ready for AI assistant integration

Tools Available (12 total)

Tool	Description
excel_read_cell	Read value from a single cell
excel_read_range	Read values from a range of cells
excel_write_cell	Write value to a single cell
excel_write_range	Write values to a range of cells
excel_list_sheets	List all worksheets in workbook
excel_create_sheet	Create a new worksheet
excel_delete_sheet	Delete a worksheet
excel_get_formula	Get formula from a cell
excel_set_formula	Set formula in a cell
excel_to_json	Export worksheet to JSON
excel_to_csv	Export worksheet to CSV
excel_info	Get workbook information and stats

Input Options

Loading a Workbook

Three ways to provide an Excel file:

1. Base64 encoded — Set excelFile to base64 string of .xlsx file
2. URL — Set excelUrl to download from URL
3. Create new — Set createNew: true for empty workbook

Tool Arguments

excel_read_cell

{
  "cell": "A1",
  "sheet": "Sheet1"  // optional, defaults to active sheet
}

excel_read_range

{
  "start_cell": "A1",
  "end_cell": "D10",
  "sheet": "Sheet1",  // optional
  "include_headers": true  // optional, treats first row as headers
}

excel_write_cell

{
  "cell": "A1",
  "value": "Hello World",
  "sheet": "Sheet1"  // optional
}

excel_write_range

{
  "start_cell": "A1",
  "data": [
    ["Name", "Age", "City"],
    ["Alice", 30, "NYC"],
    ["Bob", 25, "LA"]
  ],
  "sheet": "Sheet1"  // optional
}

excel_create_sheet

{
  "name": "NewSheet",
  "index": 0  // optional, position in workbook
}

excel_delete_sheet

{
  "name": "OldSheet"
}

excel_get_formula / excel_set_formula

{
  "cell": "C1",
  "formula": "=SUM(A1:B1)",  // for set_formula only
  "sheet": "Sheet1"  // optional
}

excel_to_json

{
  "sheet": "Sheet1",  // optional
  "include_headers": true,  // optional
  "max_rows": 1000  // optional, limit rows
}

excel_to_csv

{
  "sheet": "Sheet1",  // optional
  "max_rows": 1000  // optional
}

Output

Each run dispatches one toolCall and writes records to the run's dataset (this is a request/response actor, not a live socket server). A run emits, in order:

type	When	Contents
mcp_server_info	always	name, version, tools (the 12 tool definitions), tool_count, workbook_loaded, capabilities
tool_result	when toolCall is provided	tool, arguments, and result (see below)
workbook_saved	only after a write operation	key (output.xlsx), message
session_stats	always	stats: total_operations, reads, writes, errors

Tool Results

The tool_result.result object always includes:

• success: boolean indicating if the operation succeeded
• error: error message if it failed
• Tool-specific keys on success (e.g. value, data, sheet, formula, csv, headers, row_count)

Modified Workbooks

If you make changes (write operations), the modified workbook is automatically saved to the Actor's key-value store as output.xlsx and reported via the workbook_saved record. You can download it from there.

Examples

Read a range and export to JSON

{
  "excelUrl": "https://example.com/data.xlsx",
  "toolCall": {
    "name": "excel_to_json",
    "arguments": {
      "include_headers": true
    }
  }
}

Create new workbook and write data

{
  "createNew": true,
  "toolCall": {
    "name": "excel_write_range",
    "arguments": {
      "start_cell": "A1",
      "data": [
        ["Product", "Price", "Quantity"],
        ["Widget", 9.99, 100],
        ["Gadget", 19.99, 50]
      ]
    }
  }
}

Add a formula

{
  "excelUrl": "https://example.com/sales.xlsx",
  "toolCall": {
    "name": "excel_set_formula",
    "arguments": {
      "cell": "D2",
      "formula": "=B2*C2"
    }
  }
}

Use Cases

• AI Assistants — Enable Claude, GPT, or other AI to work with spreadsheets
• Data Processing — Extract, transform, and analyze Excel data
• Report Generation — Programmatically create Excel reports
• Automation — Integrate Excel operations into Apify workflows
• MCP Workflows — Part of larger MCP-enabled automation chains

Limitations

• One tool call per run. Each run executes a single toolCall. It is a request/response actor whose results land in the dataset — not a persistent stdio/SSE MCP server. Chain runs, or connect via Apify's Actors MCP server, for multi-step sessions.
• .xlsx only. Loads and saves .xlsx (Excel 2007+) via openpyxl. Legacy .xls, .xlsb, and password-protected files are not supported.
• Formulas are stored, not evaluated. Set formulas are written as-is; openpyxl does not compute their results, so reading a formula cell returns the formula string (or a cached value if the source file had one), not a freshly recalculated number.
• Formatting preservation is openpyxl-level. Styles, number formats, and structure that openpyxl round-trips are preserved; features openpyxl does not model (charts, pivot tables, VBA/macros, some conditional formatting) may be dropped on save.
• In-memory processing. The whole workbook is held in memory; very large files are bounded by the run's memory and timeout.
• No workbook = limited tools. Every tool except excel_info requires a workbook (excelFile, excelUrl, or createNew: true); calling one without a loaded workbook returns a success: false result rather than failing the run.

Technical Details

• Python 3.11 with openpyxl library
• No Excel required — Pure Python processing
• Supports .xlsx format (Excel 2007+)
• Preserves formulas — Formulas are stored as-is

Version

v1.0.0 — Initial release